Plan

Plan (Phase 1)

Produce a plan artifact before any code is touched. The plan-gate hook blocks Edit/Write until this file exists.

Step 1 — Classify the work item

Ask (or infer from context) which of these the request is:

• New build — a new feature or capability not previously delivered
• Fix — a correction to existing behavior
• Change request (CR) — a modification to previously agreed scope

The classification drives different validation downstream (Phase 4 Build).

Step 2 — Resolve scope

If .claude/sdlc/scope.md exists and is signed: read it and proceed. Run a quick re-validation check — if the plan task looks materially different from what scope.md describes, invoke scope-ingest in re-validate mode and surface the drift report before continuing.

If .claude/sdlc/scope.md does not exist: ask the human to point at source material (file path or paste text). Then invoke the scope-ingest agent, which produces a draft at .claude/sdlc/scope-drafts/<timestamp>.md. Show the draft to the human and wait for review. The human copies/renames it to .claude/sdlc/scope.md and signs it before the plan proceeds.

Fallback — no source material: if the human has no source to point at, ask for a one-paragraph scope statement and write .claude/sdlc/scope.md directly (existing behavior, preserved for minimal-friction cases).

Then validate the resolved scope against the work item:

• New build: confirm the request is within documented scope. If not, surface a scope-delta and ask the human whether to (a) treat as a CR, (b) expand scope, or (c) defer.
• Fix: confirm the fix addresses in-scope behavior. An out-of-scope fix is a CR in disguise.
• CR: require a change-request ID. If missing, create one under .claude/sdlc/change-requests/CR-<n>.md using templates/change-request.md and ask the human for sign-off before continuing.

See agents/scope-ingest.md for accepted source formats and draft output spec.

Step 2.5 — Domain expert check

After scope validation and before writing the plan, invoke the domain-expert skill. It runs the two-source domain lookup (project domains/ then plugin domains/), matches the task against the domain index, and — when a match is found — prepares a ## Domain context block to be appended to the plan artifact in Step 3.

If no domain matches, the skill exits silently. Do not wait for the human or prompt them unless the skill itself surfaces a medium/low-confidence match that requires confirmation.

See skills/domain-expert/SKILL.md for the full matching and output specification.

Step 3 — Write the plan

Version check (before writing). If .claude/sdlc/plans/<task-slug>.md already exists and a signed plan gate (gates/plan-<task-slug>.md) exists for it, compare the intended new content against the current plan's material fields:

• Classification (new-build / fix / change-request)
• In-scope files list
• In-scope functions list
• Out-of-scope list
• Risks & rollback section

If any material field changed, do not write yet. Prompt the human with a narrative message that names the specific change and its consequence:

Changing Classification from fix to new-build will archive the current plan as v<N> (superseded). Your existing sign-off will not carry over to v<N+1>. Continue? [Y/n]

On yes: read the current plan's Version: field (treat absent as 1 for legacy plans). Rename <task-slug>.md to <task-slug>.v<N>.md and set Status: superseded in the renamed file. Then write the new plan at <task-slug>.md with Version: <N+1> and Status: draft. Print: Saved as v<N+1>. v<N> archived at plans/<task-slug>.v<N>.md (superseded).

On no: discard the changes to material fields and resume with the current plan unchanged.

Non-material edits (prose, typos, formatting) pass silently — do not trigger this check.

Write to .claude/sdlc/plans/<task-slug>.md using templates/plan.md. Required fields:

• Task ID & classification (new-build / fix / CR + reference ID)
• Problem (1–2 sentences)
• In-scope files (explicit list — hooks enforce this)
• In-scope functions (explicit list — hooks enforce this)
• Out-of-scope (explicit "do not touch" list)
• Approach (3–5 bullets)
• Tests to add/update (function-level — only modified code gets new tests)
• Risks & rollback
• Estimate (t-shirt size or story points; see config/tools.json for convention)
• Version (start at 1; increment on each material edit of a signed plan)
• Status (draft until plan gate is signed; signed after; superseded when replaced by a newer version)

Keep it short. The plan is a contract, not a design doc — Phase 3 handles design.

Step 4 — Technology stack

For new builds, propose the stack (language, framework, major libraries, platform, data store). For fixes and CRs on existing code, record the existing stack the change lives in.

Validate compatibility:

• Language/runtime versions against existing platform
• Library licenses against project policy (if recorded)
• Data schema compatibility if the change touches data
• Auth/identity compatibility
• Deployment target compatibility

Produce a compatibility matrix as a markdown table in the plan file. Any FAIL row halts planning and requires human decision.

Step 4.5 — Scope gate (first task per project only)

If .claude/sdlc/gates/scope-<project-slug>.md does not exist, draft and sign the scope gate before proceeding to the plan gate. If the file already exists, skip this step entirely.

Derive the project slug from the project_name field in scope.md (slugify: lowercase, hyphens, no spaces). If scope.md has no project name, use the repository directory name.

Draft the scope gate at .claude/sdlc/gates/scope-<project-slug>.md using templates/scope-gate.md:

• Fill ## Scope summary — one paragraph summarising what the scope covers and what source material was used.
• Fill ## Source material — source path (or "pasted text"), extraction confidence per field, provenance pointer to the scope draft.
• Pre-tick ## Scope fields confirmed for every field that was present and reviewed in the scope draft. Leave unchecked fields that were absent or low-confidence.
• Fill ## Open items carried forward with any low-confidence or absent fields from the draft that the plan must still resolve.
• Compute gate_hash: sha256 of the file content above the ## Required sign-offs heading at this point in the draft. Write it into the gate_hash: line before presenting the gate to the human.

Ask the human to sign the scope gate (same chat sign-off prompt as a phase gate). Acceptable inputs: a URL, or no ticket REQ-SCOPE-<project-slug> for degraded mode. Write the signed gate file.

After sign-off, plan-gate.sh will stop warning about the missing scope gate on all future /plan invocations for this project.

Step 5 — Second opinion review (hard rule — cannot be skipped)

Before presenting the plan to the human, run a self-contained second-opinion review. Re-read the complete plan artifact as if encountering it for the first time and check:

1. Classification — is it unambiguously one of: new-build / fix / change-request? Any ambiguity must be resolved before proceeding.
2. In-scope files — explicit, non-empty list. "TBD" is not acceptable at gate time.
3. In-scope functions — explicit or documented as deferred (allowed before Build only).
4. Out-of-scope — not the template placeholder; must name specific things excluded.
5. Tests to add/update — non-empty; function-level.
6. Risks & rollback — non-empty; names specific failure modes and the rollback path.
7. Compatibility matrix — no unresolved FAIL rows; UNKNOWN is treated as an open item, not a pass.

If any item fails the checklist, surface the gap explicitly and ask the human to resolve it before requesting sign-off. Do not present the gate summary until all checklist items pass.

Present the second-opinion findings to the human in this format:

Second opinion — plan review
✓ / ✗ Classification: [result]
✓ / ✗ In-scope files: [result]
✓ / ✗ In-scope functions: [result]
✓ / ✗ Out-of-scope: [result]
✓ / ✗ Tests: [result]
✓ / ✗ Risks & rollback: [result]
✓ / ✗ Compatibility matrix: [result]

[If any ✗: list gaps and ask human to resolve before sign-off.]
[If all ✓: "Plan passes second-opinion review. Proceeding to sign-off."]

Step 6 — Human gate

Produce a one-screen summary of the plan and ask the human to confirm before Analyze/Design/Build proceeds. Write the confirmation to .claude/sdlc/gates/plan-<task-slug>.md using templates/gate.md — later commands check for this file.

The gate summary must show what the human is approving (scope, classification, risks) and what they are not approving (architecture, implementation approach — those belong in later phases).

What this skill must NOT do

• Do not write code.
• Do not modify files outside .claude/sdlc/.
• Do not skip the scope check, even if the task feels obvious.
• Do not approve the plan on the user's behalf — the gate file requires the human to confirm.
• Do not present the gate summary (Step 6) before completing the second-opinion review (Step 5). This is a hard rule. A plan that skips Step 5 is not ready for sign-off.

References

• templates/plan.md — plan artifact template
• templates/change-request.md — CR template
• templates/gate.md — phase-gate template
• templates/scope-gate.md — scope gate template (Step 4.5)
• agents/scope-ingest.md — scope draft producer (Step 2)
• skills/domain-expert/SKILL.md — domain context injector (Step 2.5)
• docs/SDLC.md — full phase reference

Next step hint

After writing the gate file, pipe the next_suggestions conditions to skills/_shared/next-hint.sh and print any output:

printf '%s\n' \
  'all_signoffs_present|run /analyze to produce requirements with REQ IDs' \
  'pending_signoff_for_current_user|write your sign-off at sign-offs/<REQ-ID>-<role>.md, then /analyze when all roles are covered' \
  'plan_gate_signed|run /analyze to produce requirements with REQ IDs' \
  | bash skills/_shared/next-hint.sh

Print any output verbatim. If the script outputs nothing (suppressed, faded, or no match), add nothing.