Planner

Turns a branch's git diff into a reviewable set of manual test scenarios, then correlates explorer findings back to each scenario after a run.

What it does

The planner inspects the working branch against its tracking base, summarizes the change, and proposes manual test scenarios that cover the impacted behavior.

Each scenario is persisted as a standalone spec markdown file with stable metadata — scenarioId, baseCommit, generatedFromHead, createdAt — so it can be referenced, edited, and extended across commits. Immutable meta is guarded: edits that drop or mutate a scenario's identity are rejected.

Drive it from the CLI with xqa plan (plus edit / extend / report). Diff in, specs out; findings in, correlated report out.

Where it sits

Planner lives upstream of the explorer pipeline. Diff in, specs out; findings in, correlated report out.

git diff
→
planner
→
spec markdown
Scenarios generated from the branch diff feed the explorer pipeline, which drives the simulator and emits findings.
findings.json
→
planner
→
report.json
After a run, reportRun correlates findings back to the scenarios that produced them.

Pipelines

Four entry points compose the same shell and core primitives.

generatePlan

First-time

Proposes a full scenario set for the current branch diff.

Input

  • gitContext
  • outputDirectory
  • intent, appContext
  • aiConfig

Output

  • specs: string[]
  • emptyReason?
  1. Resolve tracking base and current head
  2. Collect git diff + git status summary
  3. Fail fast on empty diff; skip comments-only / rename-only
  4. Load existing scenarios to avoid duplicate coverage
  5. Call AI, validate drafts, persist with stamped meta

editScenario

Refine

Applies user feedback to one existing spec without losing its identity.

Input

  • file
  • userFeedback
  • aiConfig

Output

  • path
  • changed: boolean
  1. Load spec and assert meta completeness
  2. Call AI edit applier with user feedback
  3. Verify immutable meta preserved
  4. Render markdown, write atomically
  5. Report whether content actually changed

extendPlan

Incremental

Appends scenarios for commits added since the plan was last generated.

Input

  • gitContext
  • outputDirectory
  • intent, appContext
  • aiConfig

Output

  • appended: string[]
  • emptyReason?
  1. Load existing plan, require non-empty
  2. Pick last spec's generatedFromHead as since-SHA
  3. Verify commit still exists, diff against head
  4. Skip on empty / non-actionable change
  5. Emit and append with since-SHA as base

reportRun

Post-run

Correlates a findings file against the scenarios that produced it.

Input

  • findingsPath
  • specsDirectory

Output

  • CorrelatedReport
  • Writes report.json
  1. Read and schema-validate findings.json
  2. Load plan, reject scenarios with incomplete meta
  3. Correlate findings by scenarioId
  4. Emit every step with status: 'unknown' (v1)
  5. Write report next to findings file

When something goes wrong

Common failure modes — what they mean for you.

Git

  • Not a git repository
  • No base branch to compare against
  • Git command failed
  • Extend base commit no longer available

Diff

  • Empty diff — nothing changed
  • Only renames or comment-only changes

AI

  • Model call failed or timed out
  • Response was not valid scenario data

Spec files

  • Could not write or read a scenario file
  • Frontmatter or sections malformed

Plan directory

  • Output directory missing (create-on-generate recovers)
  • Directory exists but has no specs to extend

Findings & edits

  • Findings missing or invalid after a run
  • An edit dropped or mutated a scenario's identity