Section 02: /create-plan Phase 0 Subsumption Classification Step

Goal: Wire §01’s routing rule into /create-plan so plan creation captures subsumption claims at the moment the plan is being designed, not as an afterthought.

Success Criteria: see frontmatter.

Implementation Sketch

/create-plan Phase 0 already does scope analysis + fork-decision. The natural insertion point for subsumption classification is between Phase 0’s fork-decision and Phase 1’s prerequisites — once the plan’s touches: is known (which subsystems are affected), candidate bugs can be enumerated.

Workflow:

1. Enumerate candidates. For each touches: path, query scripts/intel-query.sh bugs-for <subsystem> (subsystem mapping via intelligence.md §Subsystem Mapping). Fall back to git grep -l 'subsystem: <name>' bug-tracker/plans/*/00-overview.md if intel graph unavailable.
2. Filter candidates. Filter out status: closed and status: complete bugs (no value in claiming fixed bugs). Filter rule for status: in-progress bugs (per Step 4 blind-spot 6): they ARE candidates — the in-progress filter from prior plan revisions applied to active /fix-bug routing, not /create-plan rebuild routing. When a candidate is in-progress, append a MIGRATION_RACE_GUARD warning to its surfaced row.
3. Apply 3-signal test (author-confirmed) + author subsumption_evidence. For each candidate, present: bug title + symptom + filed-in subsystem + Claude’s signal-fire inference + (if in-progress) MIGRATION_RACE_GUARD warning. Author confirms via batched AskUserQuestion per subsystem (NOT per bug). Recommended option per ask-user-question.md = Claude’s best-grounded inference with rationale.
4. Capture verification_test. Per confirmed claim, locate the failing test reference: try (priority) bug-frontmatter verification_test: → bug Mission Success Criteria checklists → bug §03 TDD matrix → author-supplied. If none found, surface SUBSUMES_TEST_REF_REQUIRED AskUserQuestion.
5. Write classifications. For subsumes choices: append subsumes: [{bug, verification_test, subsumption_evidence}, ...] to plan’s 00-overview.md frontmatter; cross-write subsumed_by: plans/<name>/ on each bug; flip bug status: open|in-progress → subsumed; HISTORY entries on both sides citing the classification turn (timestamp, plan name, signals confirmed, verification_test, payload summary).

Implementation Items

• §02.1 Add Phase 0.6 (or equivalent — between fork-decision and Phase 1) Subsumption Classification step to .claude/skills/create-plan/SKILL.md. Cite routing.md §2.X (authored by §01 of this plan) as the routing SSOT. Document the step’s I/O: input = plan’s touches:; output = subsumes: frontmatter on plan + subsumed_by: cross-writes on bugs.
• §02.2 Implement subsystem-to-bug enumeration helper. Reuse intelligence.md §Subsystem Mapping table for path → subsystem mapping. Primary path: scripts/intel-query.sh bugs-for <subsystem>; graceful-degradation fallback: git grep -l 'subsystem: <name>' bug-tracker/plans/*/00-overview.md. Filter by status: include open AND in-progress; exclude closed, complete, subsumed (already claimed).
• §02.2 Implement MIGRATION_RACE_GUARD detection. For each in-progress candidate, query git log -1 --format=%H bug-tracker/plans/BUG-XX-NNN/ to detect recent activity (commit within last 7 days). Mark such candidates with the warning flag in the candidate-row payload.
• §02.3 Implement author-confirmation prompt. Batched AskUserQuestion per subsystem (NOT per bug — fan-out is a STRUCTURE:autopilot-pause-leak failure mode). Each option presents one candidate bug with classification choices: subsumes / blocker / unrelated / defer. Recommended option per ask-user-question.md rule = Claude’s best-grounded inference with one-line rationale citing which of the 3 signals fire. For in-progress + MIGRATION_RACE_GUARD candidates, the option list adds a (in-progress — race guard) annotation; recommendation accounts for the race.
• §02.3 Implement subsumption_evidence payload authoring sub-prompt. After signal confirmation, prompt for (or auto-extract from bug overview): replaced_subsystem (str), root_cause_pointer (file:line or commit SHA), verification_test_pointer (test path or test-id). Auto-extraction tries: (1) bug subsystem: field for replaced_subsystem; (2) bug §02 root cause pointer for root_cause_pointer; (3) bug Mission Success Criteria test list for verification_test_pointer. Author confirms or overrides.
• §02.3 Implement verification_test capture. Per claim, attempt to locate failing test reference: priority order = bug-frontmatter verification_test: (future field) > bug Mission Success Criteria block (e.g., BUG-04-118 lists 16 tests at bug-tracker/plans/BUG-04-118/00-overview.md:40-42) > bug §03 TDD matrix in bug-plan body > author-supplied. If none locatable, emit SUBSUMES_TEST_REF_REQUIRED AskUserQuestion with options: (a) author-supplied path (Recommended), (b) defer classification, (c) skip subsumption.
• §02.4 Implement bidirectional frontmatter writes. Plan side: subsumes: list[SubsumptionClaim] on plan’s 00-overview.md (schema field added by §05). Bug side: subsumed_by: str | null on bug’s 00-overview.md (schema field added by §05). Atomic write pair — both succeed or both rollback. Use Python tempfile + os.rename for atomic single-file writes; cross-file atomicity is best-effort via write-both-then-verify (no two-phase commit needed for filesystem writes at this granularity).
• §02.5 Implement bug status flip + HISTORY entries. Bug status: open|in-progress → subsumed (requires §05 schema enum extension to permit subsumed in OVERVIEW_STATUSES + FIX_STATUSES). HISTORY entry on both sides: “YYYY-MM-DD — Subsumed by plans/<name>/. Signals confirmed: surface=Y, non-reproduction=Y, symptom=Y. verification_test=<path>. subsumption_evidence: replaced_subsystem=<subsystem>, root_cause=<pointer>. Verification at plan-completion gate per §07.”
• §02.5 Cross-bug-blocker check. If the candidate is target of any other bug’s blocked_by: chain (grep -l "BUG-XX-NNN" bug-tracker/plans/*/00-overview.md), surface SUBSUMED_BLOCKER_DEPENDENCY warning AskUserQuestion with options: (a) co-subsume the dependent bug under same plan (Recommended when 3-signal also fires for the dependent), (b) rehome the blocker — re-point dependent’s blocked_by: to this plan, (c) skip subsumption — leave the chain intact.
• §02.6 Idempotency: re-running classification on an already-classified plan reads existing subsumes: + skips classified bugs (no double-prompt, no duplicate HISTORY entries). --called-by-orchestrator behavior: when set, skip the AskUserQuestion and return structured exit-state subsumption_classification_pending with payload {candidates: [{bug, signal_inference, race_guard, suggested_test}], subsystems: [...]} for the orchestrator to resolve.
• §02.6 Test cases: (a) plan with no candidate bugs (empty subsumes:, no prompts), (b) plan with 1 candidate (single-question prompt), (c) plan with N candidates across M subsystems (M batched prompts), (d) re-run idempotency, (e) --called-by-orchestrator deferred behavior, (f) in-progress candidate with race guard, (g) candidate target of blocked_by: chain (blocker dependency check), (h) candidate with no locatable verification_test.

Test Strategy

This section modifies /create-plan skill behavior. Test matrix:

Semantic pins:

• Positive: re-arch + non-reproduction + symptom all-confirmed → bug lands in subsumes: AND subsumed_by: cross-writes AND status flips. Reverting any one of the three writes the test fails.
• Negative: 2-of-3 signals confirmed (e.g., re-arch + non-reproduction but NOT symptom) → bug routes per /add-bug --inline 5-case dispatcher OR stays as separate tracker entry; subsumes: is NOT written. Test that the wrong-classification case is rejected, not silently absorbed.

Intelligence Reconnaissance

(2026-05-09) Section modifies .claude/skills/create-plan/SKILL.md + references files (Markdown skill body) and reads scripts/intel-query.sh (Bash) for the bug-enumeration helper. Skill bodies are not symbol-graph-indexed; intel-query.sh bugs-for <subsystem> is the Python-shipped subcommand the new step invokes (verified present per intelligence.md §How to Query table). Per compose-intel-summary.md graceful-degradation, recording graph unavailability for the skill-body edit as freeform prose; the inner subcommand call IS graph-mediated at runtime. Cross-references resolved by direct Read: /create-plan/SKILL.md (Phase 0 + Phase 0.5 feature-mode pattern verified), intelligence.md §Subsystem Mapping (path → subsystem mapping table verified), ask-user-question.md (recommended-option rule verified). Symbol-graph queries reserved for sections that touch compiler-indexed Python (§05, §06).

Cross-References

• §01 — routing rule SSOT this section consumes.
• §05 — schema fields (subsumes:, subsumed_by:) this section writes.
• /create-plan SKILL.md — host file for the new step (@-included rules + body modifications).
• .claude/rules/ask-user-question.md — recommended-option rule for the classification prompt.
• .claude/rules/skill-control-contract.md §Hybrid Contract — --called-by-orchestrator deferred-behavior protocol.

02.1 Add Subsumption Classification step to /create-plan SKILL.md

Insertion point: .claude/skills/create-plan/SKILL.md Phase 0.6 (between Phase 0.5 Feature-mode fork-decision and Phase 1 Prerequisites).

• Add a new ## Phase 0.6 — Subsumption Classification section to .claude/skills/create-plan/SKILL.md body. Reference: routing.md §2.X (authored by §01 of THIS plan).
• Document the step’s inputs: plan’s proposed touches: array; plan’s mission text (for 3-signal heuristic).
• Document the step’s outputs: subsumes: list[SubsumptionClaim] on plan’s 00-overview.md; bidirectional subsumed_by: cross-writes; bug status: flips per §02.5.
• Document --called-by-orchestrator exit-state schema: {status: "subsumption_classification_pending", candidates: [...], subsystems: [...]}.
• Add @-include reference to .claude/rules/routing.md and .claude/rules/ask-user-question.md at top of the new phase per skill-template.md §2 SSOT consumption discipline.

02.2 Implement subsystem→bug enumeration + race-guard detection

• Author .claude/skills/create-plan/references/subsumption-enumerate.md (or inline in SKILL.md if total body stays under 500 lines) — references file holds the algorithm; SKILL.md cites it.
• Implement primary enumeration: for each path in plan’s touches:, call scripts/intel-query.sh bugs-for $(map_path_to_subsystem <path>) per intelligence.md §Subsystem Mapping. Aggregate bug list across paths; dedup by bug-id.
• Implement graceful-degradation fallback: when scripts/intel-query.sh status reports unavailable, fall back to git grep -l 'subsystem: \"<name>\"' bug-tracker/plans/*/00-overview.md. Document the fallback as the canonical secondary path.
• Implement candidate filter rule: include status: open AND status: in-progress; exclude status: closed | complete | subsumed. (subsumed excluded because already-claimed bugs are not re-candidates.)
• Implement MIGRATION_RACE_GUARD: for each in-progress candidate, run git log -1 --since="7 days ago" --format=%H -- bug-tracker/plans/BUG-XX-NNN/. Non-empty result → tag candidate with race_guard: true for §02.3 prompt-rendering.

02.3 Implement 3-signal-test author-confirmation prompt + subsumption_evidence + verification_test capture

• Implement batched AskUserQuestion per subsystem. Question template: “Plan touches <subsystem>. The following bugs are candidates for subsumption: [bug list with signal-fire inference]. Classify each:” Options per bug: subsumes (Recommended when 3-of-3 fire), blocker, unrelated, defer. Maximum 4 options per AskUserQuestion schema constraint; if subsystem has >4 candidates, batch into multiple sequential questions (max 4 candidates per question, all questions emitted before any execution per skill-control-contract.md §Front-Loading Pattern).
• Implement signal-fire inference helper (Claude’s best-grounded suggestion only; mechanical inference BANNED per §01 banned pattern (c) — author confirms): heuristic checks (a) plan’s touches: ⊇ bug’s subsystem: (signal #1), (b) plan’s mission text matches bug’s reproducer description (signal #2), (c) bug’s root-cause pointer cites a path in plan’s touches: (signal #3). Render as “SUGGESTED: subsumes (signals 1+2+3 fire — verify)” or “SUGGESTED: not subsumed (only signal N fires)”.
• Implement subsumption_evidence payload authoring per confirmed claim. Auto-extract: (1) replaced_subsystem from bug’s subsystem: field; (2) root_cause_pointer from bug §02 root-cause first cite; (3) verification_test_pointer from bug Mission Success Criteria block (look for tests pass / failing test checklist items). Surface auto-extracted values in a confirmation AskUserQuestion: option (a) Accept auto-extracted (Recommended), (b) Override values (free-text per field), (c) Skip subsumption — payload incomplete.
• Implement verification_test capture. Priority chain: (1) bug verification_test: frontmatter field (future addition); (2) bug 00-overview.md Mission Success Criteria — first checklist item containing the substring test_ or tests pass (e.g., BUG-04-118’s bug-tracker/plans/BUG-04-118/00-overview.md:40-42 lists 16 test_* paths); (3) bug §03 TDD matrix; (4) author-supplied. If chain exhausts with no result, emit SUBSUMES_TEST_REF_REQUIRED AskUserQuestion: option (a) Author-supplied test path (Recommended — required for §07 verification), (b) Defer classification, (c) Skip subsumption.

02.4 Implement bidirectional frontmatter writes (plan + bug 00-overview)

• Implement plan-side write. Read plans/<name>/00-overview.md; parse YAML frontmatter; append to (or create) subsumes: list[SubsumptionClaim] array; write atomically via tempfile.NamedTemporaryFile + os.replace.
• Implement bug-side write. For each subsumed bug-id: read bug-tracker/plans/BUG-XX-NNN/00-overview.md; parse frontmatter; set subsumed_by: 'plans/<name>/'; write atomically.
• Implement atomicity guard. After both writes complete, verify by re-reading both files; if either side missing the write, ROLLBACK both (revert to pre-write state). Document the guard as best-effort filesystem atomicity (no two-phase commit; verify-then-rollback is the discipline).
• Schema validation: post-write, run python -m scripts.plan_corpus check plans/<name>/ bug-tracker/plans/BUG-XX-NNN/ and assert exit 0. If schema rejects (likely indicates §05 not yet shipped), abort the classification with a clear error citing §05 dependency.

02.5 Implement bug status flip + HISTORY entries + cross-bug-blocker check

• Implement status flip. Bug status: → subsumed. Requires §05 schema extension (OVERVIEW_STATUSES + FIX_STATUSES include subsumed). Pre-flight: read scripts/plan_corpus/schemas.py and assert subsumed is in the relevant frozenset; abort if not (cite §05 unmet dependency).
• Implement HISTORY entries. Plan side: append to 00-overview.md HISTORY block: “YYYY-MM-DD — Subsumed BUG-XX-NNN (signals: 1=Y, 2=Y, 3=Y; verification_test=<path>; payload={...}).” Bug side: append to bug’s 00-overview.md HISTORY block (or create the block if absent): “YYYY-MM-DD — Subsumed by plans/<name>/. Signals confirmed: 1=Y, 2=Y, 3=Y. Verification at plan-completion gate per §07; un-subsumes on completion-gate failure or plan abandonment.”
• Implement cross-bug-blocker check. For each subsumed bug-id, run git grep -l "blocked_by:.*BUG-XX-NNN" bug-tracker/plans/. Non-empty result → emit SUBSUMED_BLOCKER_DEPENDENCY AskUserQuestion. Options: (a) Co-subsume the dependent bug — runs §02.3+§02.4+§02.5 recursively for the dependent (Recommended when 3-signal fires for dependent too), (b) Rehome — re-point dependent’s blocked_by: from BUG-XX-NNN to plans/<name>/ (treating the plan as the new blocker via §05’s cross-validator), (c) Skip subsumption — leave the chain intact, this bug stays in tracker. Concrete reference: BUG-04-111 is blocked_by: ["BUG-04-118"] per bug-tracker/plans/BUG-04-111/00-overview.md:5-6; if BUG-04-118 is subsumed by plans/aims-burden-tracking/, this check fires and offers co-subsumption.

02.6 Idempotency + —called-by-orchestrator behavior tests

• Implement idempotency check. Re-run on a plan with non-empty subsumes:: read existing claims; for each, skip the bug-enumeration entry; deduplicate by bug-id; do not re-emit HISTORY. Emit a one-line summary: “N claims already present; M new candidates; K newly subsumed.”
• Implement --called-by-orchestrator flag handling per skill-control-contract.md §Hybrid Contract. When set: run §02.2 enumeration + §02.3 inference (without AskUserQuestion); return structured exit-state {status: "subsumption_classification_pending", candidates: [...], subsystems: [...]} to caller; do NOT write any files. Caller (/review-draft-proposal Step 12 or /migrate-feature) consumes the exit state.
• Test cases (TDD-style — author tests BEFORE implementation per CLAUDE.md §Tests That Expose Bugs):
  • (a) Plan with empty touches: → no candidates, no prompts, empty subsumes:, exit clean.
  • (b) Plan with single subsystem, single candidate → single AskUserQuestion, single classification write.
  • (c) Plan with N candidates across M subsystems → ≤4 candidates per question, M questions, all batched before execution.
  • (d) Re-run on already-classified plan → idempotent (no duplicate writes, no duplicate HISTORY).
  • (e) --called-by-orchestrator flag → no AskUserQuestion emitted; exit state returned.
  • (f) Candidate status: in-progress with recent commit → MIGRATION_RACE_GUARD warning surfaces.
  • (g) Candidate target of another bug’s blocked_by: → SUBSUMED_BLOCKER_DEPENDENCY AskUserQuestion fires.
  • (h) Candidate with no locatable test → SUBSUMES_TEST_REF_REQUIRED AskUserQuestion fires.
  • (i) §05 schema not shipped (subsumed not in OVERVIEW_STATUSES) → step aborts with clear error citing §05 dependency.

02.R Third Party Review Findings

• (no findings yet — populated post-TPR by Step 6 /tpr-review round)

02.N Completion Checklist

• All §02.1–§02.6 implementation items checked.
• Test matrix from §02.6 (a)–(i) all passing.
• python3 scripts/prose-lint.py .claude/skills/create-plan/SKILL.md .claude/skills/create-plan/references/ exit 0.
• python -m scripts.plan_corpus check exit 0 across the corpus.
• grep -nE '\(placeholder' plans/plan-bug-subsumption/section-02-create-plan-classification-step.md returns no hits.
• grep -nE '^- \[ \]' plans/plan-bug-subsumption/section-02-create-plan-classification-step.md — every remaining unchecked carries a concrete artifact pointer.
• /create-plan Phase 0.6 dry-run on a real candidate plan (e.g. plans/aims-burden-tracking/) demonstrates: enumeration runs; AskUserQuestion fires per subsystem; subsumption_classification_pending exit state under --called-by-orchestrator.
• §05 OVERVIEW_STATUSES includes subsumed (verified by grep "subsumed" scripts/plan_corpus/schemas.py).
• Section frontmatter status: flipped not-started → complete; 00-overview.md mission criteria checkbox for §02 flipped [x]; index.md row updated.
• (NOT-APPLICABLE:) compiler_repo/test-all.sh — skill-infra-docs plan, no compiler crate touched.
• (NOT-APPLICABLE:) /impl-hygiene-review — skill-infra-docs plan, no compiler Rust source touched.