PRD template calibration

[Dimwiddle]

Users should have a simple way of matching their existing PRD.md in to SpecLeft readable feature units.

prd-template.yml can be modified freely to match the owners current PRD. This could be automated by parsing the existing PRD.md and adding to the template.

Let the user define the headers for features and scenarios in the CLI.

Good way to trial assisted discovery.

Benefits

• Higher accuracy converting PRD in to feature units -> test skeletons.
• Higher traceability
• DX enhancement: Less manual work for users to migrate an existing PRD.md in to feature units

Workflow

CLI Steps:

specleft plan calibrate --interactive
Currently reading product requirements from ./PRD.md. Header levels found: 4...
'# Product overview'
'## Login authentication', '## Things to consider (not a requirement)'
'### Architecture overview'
'#### User login success', '#### User logins with unexpected username (out of scope)'

Feature level heading [2 - ## Login Authentication ]:
Exclude title patterns from features: not a requirement
Scenario level heading [3 - ### Architecture overview]: 4
Exclude title patterns from scenarios: out of scope

[Dimwiddle]

Issue #93 Plan: Brownfield PRD Calibration for Onboarding

Summary

Add a calibration workflow that turns an existing PRD.md structure into a usable SpecLeft template with minimal manual YAML editing, then uses existing specleft plan generation.

Feasibility is high because the repo already has:

• PRD parsing and heading analysis in /Users/rkakengi/coding_projects/specleft/src/specleft/commands/plan.py
• Template schema and loader in /Users/rkakengi/coding_projects/specleft/src/specleft/templates/prd_template.py
• Existing onboarding path and docs around specleft plan

Main gap is UX and calibration persistence, not parser fundamentals.

Product Decisions Locked

• Flow: two-step wizard (specleft plan calibrate --interactive then specleft plan)
• Persistence: preview + confirm overwrite of .specleft/templates/prd-template.yml
• MVP scope: structure calibration only (levels + include/exclude matching), not deep semantic inference
• CI/agent support: include non-interactive flags in v1
• Post-step: suggest next command, do not auto-run test generation
• Effectiveness KPI: reduce manual editing effort vs current template flow

Public Interface Changes

1. CLI command tree:

• Keep existing specleft plan behavior unchanged.
• Add specleft plan calibrate subcommand.

2. New CLI surface:

• specleft plan calibrate --from PATH --template-out PATH --interactive --feature-level INT --scenario-level INT[,INT] --exclude-feature TEXT (repeatable) --exclude-scenario TEXT (repeatable) --write --dry-run --format [table|json]
• Default: dry preview unless --write (interactive mode asks confirmation before writing).

3. Template schema additions (backward compatible):

• Add scenario-level excludes (currently missing).
• Add substring-based excludes to support phrases like “out of scope” and “not a requirement”.

Data/Type Changes

In /Users/rkakengi/coding_projects/specleft/src/specleft/templates/prd_template.py:

• Extend PRDFeaturesConfig with exclude_contains: list[str] = []
• Extend PRDScenariosConfig with:
  • exclude: list[str] = []
  • exclude_contains: list[str] = []
• Keep existing fields and defaults valid; no breaking changes to existing templates.

In /Users/rkakengi/coding_projects/specleft/src/specleft/commands/plan.py:

• Update analysis and extraction logic to respect both feature and scenario excludes (exact + contains).
• Ensure exclusion logic is applied consistently in --analyze and generation paths.

Implementation Design

1. Refactor plan command into a Click group while preserving legacy behavior:

• Convert plan to @click.group(invoke_without_command=True).
• Move current behavior into internal _run_plan(...).
• If no subcommand invoked, execute _run_plan(...) exactly as today.

2. Add calibration module:

• New file /Users/rkakengi/coding_projects/specleft/src/specleft/commands/plan_calibrate.py with:
  • heading inventory extraction by level
  • default level suggestion heuristics
  • template merge/render helper
  • write/backup helper

3. Calibration interaction flow:

• Read PRD.
• Show detected heading levels and sample headings.
• Propose defaults:
  • feature level: most likely capability level from heading distribution
  • scenario levels: next deeper level(s) with highest scenario-like density
• Collect excludes for features/scenarios (contains-based terms).
• Preview resulting YAML + analyze summary.
• Confirm overwrite (interactive) or require --write (non-interactive).
• Write template to .specleft/templates/prd-template.yml and create timestamped backup if file exists.
• Print recommended next commands:
  • specleft plan --template ...
  • specleft test skeleton --features-dir ...

4. JSON output contract for calibrate:

• include detected levels, selected values, exclusions, template path, write status, backup path, warnings, and analyze summary.

Test Plan

1. Command tests:

• Add /Users/rkakengi/coding_projects/specleft/tests/commands/test_plan_calibrate.py covering:
  • missing PRD handling
  • interactive successful calibration + confirmation
  • non-interactive deterministic flags
  • dry-run vs write behavior
  • overwrite backup creation
  • JSON payload correctness

2. Regression tests:

• Update /Users/rkakengi/coding_projects/specleft/tests/commands/test_plan.py to ensure:
  • specleft plan unchanged
  • scenario excludes affect extraction and analyze results correctly

3. Template validation tests:

• Update /Users/rkakengi/coding_projects/specleft/tests/commands/test_prd_template.py for new fields/defaults/loading.

4. Acceptance tests:

• Extend planning acceptance coverage in /Users/rkakengi/coding_projects/specleft/tests/acceptance/test_feature-1-planning-mode.py (or add a dedicated feature acceptance file) for end-to-end brownfield calibration flow.

Docs/Onboarding Updates

• Update /Users/rkakengi/coding_projects/specleft/docs/cli-reference.md with specleft plan calibrate.
• Update /Users/rkakengi/coding_projects/specleft/GET_STARTED.md with a brownfield onboarding path:
  1. calibrate template
  2. generate features
  3. generate skeleton tests

Effectiveness Validation Plan (KPI-Driven)

Evaluate manual-edit reduction against current baseline:

1. Build a small PRD corpus (repo fixtures + representative brownfield samples).
2. Compare baseline (plan --analyze + manual YAML edits) vs new calibration flow.
3. Track:

• number of manual YAML edits before first acceptable output
• number of manual spec-file corrections after generation

4. Success threshold:

• at least 50% reduction in manual edits on median sample.

Assumptions and Defaults

• Existing specleft plan users must see no behavior change.
• Template schema remains version 1.0 for additive fields only.
• No AI/LLM dependency added in this iteration.
• Calibration does not generate tests automatically.

[Dimwiddle]

gh issue comment 93 --repo SpecLeft/specleft --body '

Issue #93 Plan: Brownfield PRD Calibration for Onboarding (Task Checklist)

Summary

Implement specleft plan calibrate for brownfield onboarding, preserve existing specleft plan behavior, and add the analyze-mode CTA line:
Increase planned feature coverage by calibrating your current PRD with the prd-template.yml. Command: specleft plan calibrate

Implementation Tasks

• Refactor /Users/rkakengi/coding_projects/specleft/src/specleft/commands/plan.py so plan can host subcommands while preserving current default specleft plan execution path.
• Add plan calibrate command implementation (new module, wired into CLI command tree) with interactive and non-interactive options.
• Implement calibration detection flow (heading levels, feature/scenario candidates, exclusion terms) and template preview output.
• Implement template persistence with confirm-before-overwrite and backup of existing .specleft/templates/prd-template.yml.
• Extend template model in /Users/rkakengi/coding_projects/specleft/src/specleft/templates/prd_template.py for scenario exclusions and contains-based exclusions (backward compatible).
• Update analysis/extraction logic in /Users/rkakengi/coding_projects/specleft/src/specleft/commands/plan.py to respect new exclusion fields.
• Add the required one-line CTA to table output for specleft plan --analyze in /Users/rkakengi/coding_projects/specleft/src/specleft/commands/plan.py.
• Keep JSON output contract stable for existing plan --analyze consumers (no breaking payload changes).

Testing Tasks

• Create /Users/rkakengi/coding_projects/specleft/tests/commands/test_plan_calibrate.py with unit/CLI coverage:
• missing PRD handling
• interactive calibration flow
• non-interactive deterministic flags
• dry-run vs write behavior
• overwrite + backup behavior
• JSON output validity
• Update /Users/rkakengi/coding_projects/specleft/tests/commands/test_plan.py:
• assert new analyze CTA line appears in table output
• verify existing plan behavior unchanged
• verify exclusion logic integration for analyze/generation paths
• Update /Users/rkakengi/coding_projects/specleft/tests/commands/test_prd_template.py:
• new fields default correctly
• YAML loading/validation includes new fields
• backward compatibility for existing templates
• Add/extend acceptance tests in /Users/rkakengi/coding_projects/specleft/tests/acceptance/test_feature-1-planning-mode.py (or new acceptance file):
• end-to-end calibration workflow
• analyze CTA line assertion
• no unintended file mutations outside expected outputs

Docs Tasks

• Update /Users/rkakengi/coding_projects/specleft/docs/cli-reference.md for specleft plan calibrate command/options.
• Update /Users/rkakengi/coding_projects/specleft/GET_STARTED.md with brownfield onboarding flow (plan calibrate → plan → test skeleton).

Acceptance/Done Criteria

• specleft plan existing flows pass unchanged.
• specleft plan --analyze prints required CTA line in table mode.
• specleft plan calibrate produces usable template output for brownfield PRDs.
• All command, template, and acceptance tests pass.
  '