plan-change

This command:

• Discovers or confirms the workItemRef (e.g., PDEV-123, GH-456) by scanning existing change specs or querying the tracker.
• Orients itself in the repository and high-level documentation under doc/spec/ and related docs.
• Systematically elicits and refines all information needed by /write-spec (WHY, outcomes, boundaries, contracts, risks, NFRs, etc.).
• Concludes with a compact <change_planning_summary> plus a clear recommendation to invoke /write-spec <workItemRef>.

This command never writes files or modifies Git state; it operates purely via conversational planning and read-only repository inspection.

<workItemRef_resolution> Primary goal: determine the canonical workItemRef for this planning session.

Resolution rules:

1. If workItemRefHint is provided:

   • Validate format: uppercase prefix + hyphen + digits (e.g., PDEV-123, GH-456).
   • Treat as proposed workItemRef; ask user to confirm or override.

2. If no workItemRefHint:

   • Discover existing specs by scanning: doc/changes/**/chg-*-spec.md.
   • For each match, parse the workItemRef segment (e.g., chg-PDEV-123-spec.md → PDEV-123).
   • Propose creating a new ticket via @pm or ask user to provide an existing reference.
   • If user provides a new reference, validate format and confirm.

3. Once confirmed, use workItemRef consistently in all summaries and handoff commands.

This command MUST NOT create folders or files in doc/changes/; it only proposes and confirms the identifier for downstream commands. </workItemRef_resolution>

<context_sources> The planning agent may read from the repository to ground questions, but must not modify files.

Primary sources:

• doc/spec/**: system-level and feature-level specifications.
• doc/overview/**: domain and product overview documents.
• doc/decisions/**: architecture decision records.
• doc/domain/**, doc/diagrams/**: architecture, flows, constraints.
• Existing change specs under doc/changes/**/chg-*-spec.md for related changes.

Usage rules:

• When user describes the change, infer domain keywords and search documentation.
• Summarize only relevant parts in concise bullets; do not paste large documents.
• Quote document titles and short excerpts; ask user to confirm context anchors.
• Treat existing specs and ADRs as authoritative constraints unless explicitly revisiting. </context_sources>

<session_flow>

1. Initialization & orientation

   • Confirm single repository scope and target service/app.
   • Resolve and confirm workItemRef using workItemRef_resolution.
   • Ask for short, plain-language description of the desired change.
   • If ideaSeed provided, restate for confirmation.

2. Clarify problem and context

   • Elicit: current state, pain points, affected users, triggers, constraints.
   • Probe for singular, measurable problem statement.
   • Identify change type: feat|fix|refactor|docs|test|chore|perf|build|ci|revert|style.

3. Define goals and success metrics

   • Separate: business goals, user goals, operational goals.
   • For each goal, elicit measurable success metric (baseline, target, window).