[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval.
[BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends.
[BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason.
[BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.
Quick Summary
Goal: Force every assumption-laden plan decision and every preservation-critical behavior through explicit user confirmation BEFORE implementation — by interviewing the user with critical questions that validate assumptions and surface issues — so no unstated assumption silently reaches code.
Summary:
- Purpose: validate a finished plan via a critical-questions interview so every assumption-laden decision and every preservation-critical behavior is user-confirmed BEFORE implementation — no unstated assumption silently reaches code.
- Main steps (run in order): Phase 0 Detect Plan Type → resolve plan path (
$ARGUMENTS / ## Plan Context / ask) → load mode + questions range as hard constraints → Phase 0.5 resolve Applicability / Plan Gate → Step 1 Read plan.md + all phase-*.md, flag decisions/assumptions/risks/tradeoffs → Step 2 Extract topics across 9 categories (Applicability, Architecture, Assumptions, Tradeoffs, Risks, Scope, New Tech/Lib, Test Specs, Preservation) → Step 3 Generate questions (2-4 concrete options each, surface implicit decisions) → Step 4 Interview via AskUserQuestion (≤4 per call) → Step 5 Document answers → offer implement/refine/skip.
- Phase 0 weights everything: plan type (bugfix/feature/migration/refactor/other) decides which question categories fire; any fix/bug/regression/broken/defect keyword makes the Preservation question BLOCKING — never skip it.
- The output is a REAL interview, not a self-answer: honor the
questions MIN-MAX range from ## Plan Context, give 2-4 concrete options per question, treat the Preservation "Unsure" answer as BLOCKED → route to /plan; if the plan adds new tech/packages, probe whether alternatives were evaluated before accepting the choice.
- Persist results narrowly: add ONLY a
## Validation Summary (confirmed decisions + action items) to plan.md — NEVER edit phase files; close by offering implement/refine/skip via AskUserQuestion.
- Applicability is mandatory for every plan: read
.claude/skills/shared/product-roadmap-contract.md, verify the plan's branch-specific ## Plan Gate, and ask the owner to confirm the embedded slice/decomposition, explicit roadmap outcome, framework technical outcome, or EXEMPT boundary plus non-goals, scenario proof, commands, evidence, and approval. BLOCKED, OPEN, MISSING, or REQUIRED cannot be silently upgraded.
Workflow:
- Detect Plan Type — Classify plan (bugfix/feature/migration/refactor) to weight question categories
- Read Plan — Parse plan.md + phase files for decisions, assumptions, risks
- Extract Topics — Scan architecture, assumptions, tradeoffs, risks, scope keywords
- Generate Questions — Formulate concrete questions with 2-4 options each
- Interview User — Present questions using configured count range
- Document Answers — Add Validation Summary section to plan.md
Key Rules:
- MUST ATTENTION use
AskUserQuestion — NEVER auto-decide on behalf of user — why: the user owns every assumption-laden choice, not the agent
- Ask ONLY about genuine choices affecting implementation — NEVER about non-decision points — why: noise questions burn the interview budget and erode trust
- Bugfix plans ALWAYS trigger the Preservation question (keywords: fix, bug, regression, broken, defect) — why: an unverified preserved-correctness invariant is a silent regression
- Persist via a
## Validation Summary on plan.md — NEVER modify phase files — why: phase files are the plan's source of truth; validation is a read-then-annotate pass
- For embedded, explicit-roadmap, framework/library, or EXEMPT plans, include the final applicability status and exact owning paths in that same summary; use each branch only when the plan records its required evidence and owner.
First Principle — Easy to Change
The success metric of every coding decision is future change cost.
DRY, SRP, abstraction, design patterns, naming, layering, tests — every
technique exists to serve one goal: making the next change cheaper.
Evaluating code, refactor, test, abstraction, ask:
does this make next change cheaper or more expensive?
- Reject "best practices" raising change cost (premature abstraction,
speculative generality, leaky indirection, ceremony without payoff).
- Name real enemies in findings: coupling, hidden state, duplicated
knowledge, unclear intent, irreversible decisions exposed too early.
- Simpler design easy to change beats sophisticated design that isn't.
Apply this lens before invoking any specific rule, pattern, or checklist
below — if a downstream rule raises change cost, this principle wins.
Phase 0: Detect Plan Type
Classify plan type BEFORE generating questions — drives question category weighting:
| Plan Type |
Detection |
Mandatory Extra Categories |
| Bugfix |
Title/frontmatter: fix, bug, regression, broken, defect |
Preservation (BLOCKING) |
| Feature |
New capability, no fix keywords |
Architecture, Assumptions, Test Specs |
| Migration |
Schema change, EF migration, data move |
Risks, Preservation, Scope |
| Refactor |
Restructure/clean up, no behavior change |
Preservation, Tradeoffs |
| Other |
None of above |
Architecture, Scope |
Bugfix detection is BLOCKING — NEVER skip Preservation question when fix/bug/regression/broken/defect keywords present.
Plan Resolution
$ARGUMENTS provided → use that path
- Check
## Plan Context section → use active plan path
- No plan found → ask user to specify path or run
/plan first
Phase 0.5: Applicability / Plan Gate
Before extracting technical questions, read .claude/skills/shared/product-roadmap-contract.md and classify the plan's branch.
- For an embedded large-idea plan, read the owning PBI/spec and verify the complete
large_idea_decomposition block, selected slice, non-goals/deferred owners, and conditional scenario artifact when needed. Do not require docs/product-roadmap.md or a product milestone.
- For an explicit-roadmap plan, read
docs/product-roadmap.md, the selected milestone's scope brief, and scenario-analysis.md.
- For a framework/library plan, read the technical scope, operational scenarios, generated-carrier evidence, and commands.
- Verify
plan.md contains one ## Plan Gate with matching branch/outcome/boundaries, explicit non-goals, defined lifecycle terms when applicable, the branch decision state, known or explicitly inapplicable skeleton/configuration, build/test/run commands, redacted evidence, and Human approval: APPROVED.
- Missing upstream artifacts or
BLOCKED/OPEN/MISSING/REQUIRED values create a blocking Applicability question. Do not begin implementation or recommend implement while it remains unresolved.
- For an isolated brownfield change or bugfix, verify the shared contract's EXEMPT branch: the scope brief and plan contain the reason/owner, the sibling scenario exists when required, roadmap/milestone are explicitly
EXEMPT, product decisions use explicit N/A rationale, and commands/evidence/approval are known. Retain all existing preservation/spec/test/review questions.
Configuration (from injected context)
Check ## Plan Context section:
mode — auto/prompt/off behavior
questions — range like 3-8 (min-max)
Use as hard constraints.
Workflow
Step 1: Read Plan Files
Read plan directory:
plan.md — overview + phases list
phase-*.md — all phase files
- Flag: decision points, assumptions, risks, tradeoffs
Step 2: Extract Question Topics
| Category |
Keywords |
| Architecture |
approach, pattern, design, structure, database, API |
| Assumptions |
assume, expect, should, will, must, default |
| Tradeoffs |
tradeoff, vs, alternative, option, choice, either/or |
| Risks |
risk, might, could fail, dependency, blocker, concern |
| Scope |
phase, MVP, future, out of scope, nice to have |
| New Tech/Lib |
install, add package, new dependency, npm install, dotnet add, unfamiliar framework names |
| Test Specs |
TC-, test case, coverage, TDD, test specification |
| Preservation |
auto-trigger on bugfix keywords in title/frontmatter — scan Preservation Inventory section |
| Product Readiness |
roadmap-applicable or EXEMPT plan — scan the applicable ## Plan Gate branch, scope/scenario refs, non-goals, definitions, evidence, and human approval |
Step 3: Generate Questions
Format rules:
- 2-4 concrete options per question
- Mark recommended with "(Recommended)" suffix
- "Other" option automatic — do NOT add
- Surface implicit decisions
For a roadmap-applicable plan, ask a Product Readiness question before lower-level choices:
Does the plan implement the owning slice/outcome or technical boundary exactly, with the stated non-goals, lifecycle definitions where applicable, scenario proof, known skeleton/commands, redacted evidence, and human approval?
Offer concrete choices such as: Yes, approve the Plan Gate (Recommended); No, revise the scope/plan; A product decision remains open; This plan is an explicitly accepted isolated-change exemption. Never answer this question from the plan author's confidence alone.
Examples:
Category: Architecture
Question: "How should validation results be persisted?"
Options:
1. Save to plan.md frontmatter (Recommended) — updates existing plan
2. Create validation-answers.md — separate answers file
3. Don't persist — ephemeral validation only
Category: Assumptions
Question: "Plan assumes API rate limiting not needed. Correct?"
Options:
1. Yes, not needed for MVP
2. No, add basic rate limiting now (Recommended)
3. Defer to Phase 2
Category: Preservation (MANDATORY when title/frontmatter: fix, bug, regression, broken, defect)
Question: "List 2-3 inputs where CURRENT code is correct. Will fix change behavior on any?"
Options (multi-select):
1. "Current code correct on: {input A}. Fix preserves behavior." (Recommended)
2. "Current code correct on: {input B}. Fix CHANGES behavior because: {justification}"
3. "Current code has NO preserved-correctness inputs — every input was broken" (rare; requires confirmation)
4. "Unsure — need to investigate" (STOP: run /plan preservation analysis)
Follow-up rules:
- Option 2 selected →
plan.md Preservation Inventory MUST cite Preservation TC asserting new behavior is intended
- Option 4 selected → return BLOCKED status, recommend
/plan before proceeding
- Option 3 selected →
AskUserQuestion follow-up: "Confirm: current code has NO preserved invariant? [Yes, every input broken / No, missed some — re-investigate]"
Step 4: Interview User
Use AskUserQuestion — NEVER skip or auto-answer.
Rules:
- Use question count from
## Plan Context → Validation: mode=X, questions=MIN-MAX
- Group related questions (max 4 per tool call)
- Focus: assumptions, risks, tradeoffs, architecture
- MANDATORY IMPORTANT MUST ATTENTION: if plan introduces new tech/packages, ask: "Plan uses {lib}. Were alternatives evaluated? Confirm choice or research more?"
Step 5: Document Answers
Add ## Validation Summary to plan.md:
## Validation Summary
**Validated:** {date}
**Questions asked:** {count}
### Applicability
- **Branch:** DECOMPOSITION-EMBEDDED | EXPLICIT-ROADMAP | FRAMEWORK-LIBRARY | EXEMPT | BLOCKED
- **Owning artifact / roadmap:** `{paths}` or `NOT APPLICABLE — embedded/framework/EXEMPT`
- **Slice / milestone / technical outcome:** `{ID and outcome}`
- **Scope handoff / scenarios:** `{paths or conditional N/A}`
- **Plan Gate:** DECOMPOSITION-EMBEDDED | READY | FRAMEWORK-LIBRARY | EXEMPT | BLOCKED
- **Human approval:** APPROVED | REQUIRED
### Confirmed Decisions
- {decision 1}: {user choice}
- {decision 2}: {user choice}
### Action Items
- [ ] {changes needed based on answers}
NEVER modify phase files — only document what needs updating.
Output
After validation:
- Questions asked count
- Key decisions confirmed
- Items flagged for plan revision
- Recommendation: proceed to implementation OR revise plan first
Next Steps
MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing, use AskUserQuestion to present:
- "/feature-implement (Recommended)" — Begin implementation with validated plan
- "/refine" — If plan needs PBI refinement first
- "Skip, continue manually" — User decides
[BLOCKING] MUST ATTENTION use AskUserQuestion to interview user. Completing without asking ≥1 question = violation.
[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. For simple tasks, AI MUST ATTENTION ask user whether to skip.
External Memory: Complex/lengthy work → write findings + results to plans/reports/ — prevents context loss.
Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim requires file:line proof or traced evidence with confidence % (>80% act, <80% verify first).
Nested Task Expansion Contract — For workflow-step invocation, the [Workflow] ... row is only a parent container; the child skill still creates visible phase tasks.
- Call
TaskList first. If a matching active parent workflow row exists, set nested=true and record parentTaskId; otherwise run standalone.
- Create one task per declared phase before phase work. When nested, prefix subjects
[N.M] /skill-name — phase.
- When nested, link the parent with
TaskUpdate(parentTaskId, addBlockedBy: [childIds]).
- Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.
- Mark exactly one child
in_progress before work and completed immediately after evidence is written.
- Complete the parent only after all child tasks are completed or explicitly cancelled with reason.
Blocked until: TaskList done, child phases created, parent linked when nested, first child marked in_progress.
Task Tracking & External Report Persistence — Bootstrap this before execution; then run project-reference doc prefetch before target/source work.
- Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first.
- Mark one task
in_progress before work and completed immediately after evidence; never batch transitions.
- For plan/review work, create
plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md before first finding.
- Append findings after each file/section/decision and synthesize from the report file at the end.
- Final output cites
Full report: plans/reports/{filename}.
Blocked until: task breakdown exists, report path declared for plan/review work, first finding persisted before the next finding.
Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.
Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.
Sequential Thinking Protocol — Structured multi-step reasoning for complex/ambiguous work. Use when planning, reviewing, debugging, or refining ideas where one-shot reasoning is unsafe.
Trigger when: complex problem decomposition · adaptive plans needing revision · analysis with course correction · unclear/emerging scope · multi-step solutions · hypothesis-driven debugging · cross-cutting trade-off evaluation.
Format (explicit mode — visible thought trail):
Thought N/M: [aspect] — one aspect per thought, state assumptions/uncertainty
Thought N/M [REVISION of Thought K]: ... — when prior reasoning invalidated; state Original / Why revised / Impact
Thought N/M [BRANCH A from Thought K]: ... — explore alternative; converge with decision rationale
Thought N/M [HYPOTHESIS]: ... then [VERIFICATION]: ... — test before acting
Thought N/N [FINAL] — only when verified, all critical aspects addressed, confidence >80%
Mandatory closers: Confidence % stated · Assumptions listed · Open questions surfaced · Next action concrete.
Stop conditions: confidence <80% on any critical decision → escalate via AskUserQuestion · ≥3 revisions on same thought → re-frame the problem · branch count >3 → split into sub-task.
Implicit mode: apply methodology internally without visible markers when adding markers would clutter the response (routine work where reasoning aids accuracy).
Deep-dive: see /sequential-thinking skill (.claude/skills/sequential-thinking/SKILL.md) for worked examples (API design, debugging, architecture), advanced techniques (spiral refinement, hypothesis testing, convergence), and meta-strategies (uncertainty handling, revision cascades).
Project Reference Docs Gate (static JIT) — Run after task-tracking bootstrap and immediately before target/source file reads, grep, edits, tests, or analysis. Project docs override generic framework assumptions; hooks may remind or accelerate this gate, but never prove that it ran.
- Identify scope: file types, domain area, and operation.
- Read
docs/project-config.json first — the project's machine-readable map. It is the single source of truth for THIS repo (modules/paths, framework + search keywords, test/E2E/integration run-commands, design system, architecture rules, workflow patterns); ground exact paths, run-commands, and conventions on it before investigating, planning, or coding — never assume framework defaults (CLAUDE.md + reference docs are derived from it). If it — or the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any required reference doc — is missing or stale, auto-run /project-init or the narrow route (/project-config, /docs-init, /scan-all, /scan --target=<key>, /claude-md-init) first; if Codex mirrors or AGENTS.md are stale, ask the user to run /sync-codex (never auto-run it).
- Required docs by trigger: always
docs/project-reference/lessons.md; doc lookup docs-index-reference.md; review code-review-rules.md; backend/CQRS/API backend-patterns-reference.md; domain/entity domain-entities-reference.md; frontend/UI frontend-patterns-reference.md; styles/design scss-styling-guide.md + design-system/design-system-canonical.md; integration tests integration-test-reference.md; E2E e2e-test-reference.md; feature docs/specs feature-spec-reference.md + spec-system-reference.md + spec-principles.md; behavior/public-contract/spec-test-code sync workflow-spec-test-code-cycle-reference.md; derived spec index/ERD/reimplementation guides spec-system-reference.md + source Feature Specs under docs/specs/; architecture/new area project-structure-reference.md.
- Read every required doc, then before target work state:
Reference docs read: ... | Not applicable: .... After compaction, resume, delegation, or a material context change, repeat the route and restate the set; prior conversation and hook output are not proof of current loading.
Ready when: scope evaluated, docs/project-config.json consulted, required docs checked/read or setup route completed, lessons.md confirmed, citation emitted.
Understand Code First — HARD-GATE: Do NOT write, plan, or fix until you READ existing code.
- Search 3+ similar patterns (
grep/glob) — cite file:line evidence
- Read existing files in target area — understand structure, base classes, conventions
- Run
python .claude/scripts/code_graph trace <file> --direction both --json when .code-graph/graph.db exists
- Map dependencies via
connections or callers_of — know what depends on your target
- Write investigation to
.ai/workspace/analysis/ for non-trivial tasks (3+ files)
- Re-read analysis file before implementing — never work from memory alone. — why: long context drifts from the file; the file is ground truth
- NEVER invent new patterns when existing ones work — match exactly or document deviation. — why: divergent patterns fragment the codebase and slow every future reader
BLOCKED until: - [ ] Read target files - [ ] Grep 3+ patterns - [ ] Graph trace (if graph.db exists) - [ ] Assumptions verified with evidence
Plan Quality — Every plan phase MUST ATTENTION include test specifications.
- Add
## Test Specifications section with TC-{FEATURE}-{NNN} IDs to every phase file
- Map every functional requirement to ≥1 TC (or explicit
TBD with rationale)
- TC IDs follow
TC-{FEATURE}-{NNN} format — reference by ID, never embed full content
- Before any new workflow step: call
TaskList and re-read the phase file
- On context compaction: call
TaskList FIRST — never create duplicate tasks
- Verify TC satisfaction per phase before marking complete (evidence must be
file:line, not TBD)
- Purpose-oriented naming: For every planned public or cross-layer contract, port, interface, module, or adapter, name the consumer-visible capability or domain purpose; keep provider, framework, and transport names in concrete implementations (
IStorage/Storage → AzureBlobStorage). — why: a contract name should survive an implementation swap.
- Contract-fit gate: Check the proposed name against its callers and all implementations; use a narrower purpose name when a broad name overpromises (
IObjectStore or DocumentStore instead of IStorage when the behavior is narrower). — why: abstraction names must describe the actual contract, not hide a mismatch.
- No speculative abstraction: Plan an interface or port only when a real boundary, substitution need, or multiple meaningful implementations justifies it; keep a concrete type when it is the honest contract. — why: an unnecessary abstraction adds indirection and a second name without reducing change cost.
- Language convention: Preserve the repository's naming syntax (
I prefix where the language/project uses it); never force I or Interface markers across languages. — why: semantic purpose is portable, syntax is not.
- Foundation obligations — when the plan CREATES or CHANGES how the project is built, run, tested, or checked (build or CI configuration, test harness, containerization, toolchain/dependency management, module boundaries, quality tooling): run
SYNC:engineering-foundation-gate — its seven dimensions F1-F7, the four profile axes and the warranting matrix are in .claude/docs/engineering-foundation-catalog.md, which the plan reads directly when no carrier of that gate ran upstream — and carry every dimension it marks warranted into the plan as an explicit phase with acceptance criteria — never as an assumption that someone handles it later. Record each dimension deliberately skipped, with the reason. — why: a plan that stands up a foundation and silently omits a warranted dimension makes that omission permanent and invisible; foundations cost near nothing at creation and a great deal to retrofit.
Mode: TDD-first → reference existing TCs with Evidence: TBD. Implement-first → use TBD → /spec [mode=tests] fills after.
Cross-Service Check — Microservices/event-driven: MANDATORY before concluding investigation, plan, spec, or feature doc. Missing downstream consumer = silent regression.
| Boundary |
Grep terms |
| Event producers |
Publish, Dispatch, Send, emit, EventBus, outbox, IntegrationEvent |
| Event consumers |
Consumer, EventHandler, Subscribe, @EventListener, inbox |
| Sagas/orchestration |
Saga, ProcessManager, Choreography, Workflow, Orchestrator |
| Sync service calls |
HTTP/gRPC calls to/from other services |
| Shared contracts |
OpenAPI spec, proto, shared DTO — flag breaking changes |
| Data ownership |
Other service reads/writes same table/collection → Shared-DB anti-pattern |
Per touchpoint: owner service · message name · consumers · risk (NONE / ADDITIVE / BREAKING).
BLOCKED until: Producers scanned · Consumers scanned · Sagas checked · Contracts reviewed · Breaking-change risk flagged
AI Mistake Prevention — Failure modes to avoid on every task:
Re-read files after context changes. Context compaction, resume, or long-running work can make memory stale; verify current files before acting.
Verify generated content against source evidence. AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing.
Check downstream references before deleting or renaming. Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first.
Trace the full impact chain after edits. Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done.
Verify ALL affected outputs, not just the first. One green check is not all green checks; validate every output surface the change can affect.
Assume existing values are intentional — ask WHY before changing OR flagging one as a defect. Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard.
Surface ambiguity before acting — don't pick silently. Multiple valid interpretations require an explicit question or stated assumption with risk.
Assert the outcome your system owns, not the intermediate state your infrastructure owns. When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure.
Keep shared guidance role-relevant. Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.
IMPORTANT MUST ATTENTION search 3+ existing patterns and read code BEFORE any modification. Run graph trace when graph.db exists.
- MANDATORY IMPORTANT MUST ATTENTION cite
file:line evidence for every claim. Confidence >80% to act, <60% = do NOT recommend.
IMPORTANT MUST ATTENTION include ## Test Specifications with TC IDs per phase. Call TaskList before creating new tasks.
IMPORTANT MUST ATTENTION microservices/event-driven: scan producers, consumers, sagas, contracts in task scope. Per touchpoint: owner · message · consumers · risk (NONE/ADDITIVE/BREAKING). Missing consumer = silent regression.
MUST ATTENTION apply critical + sequential thinking — every claim needs appropriate traced evidence (file:line for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence.
MUST ATTENTION apply sequential-thinking — multi-step Thought N/M, REVISION/BRANCH/HYPOTHESIS markers, confidence % closer; see /sequential-thinking skill.
MUST ATTENTION apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting.
- MANDATORY Bootstrap task tracking before target work; transition one task at a time.
- MANDATORY Persist plan/review findings to
plans/reports/ incrementally and synthesize from disk.
- MANDATORY Before investigating, planning, or coding, read
docs/project-config.json (the project map: modules/paths, run-commands, conventions, architecture/workflow rules) + the required project-reference docs, and cite Reference docs read: ....
- MANDATORY Load detail just in time immediately before the first target read/grep/edit/test; hooks may provide a pointer, but a hook event or prior turn is never evidence that the current files were read.
- MANDATORY Always include
lessons.md; project config + conventions override generic framework defaults.
- MANDATORY If project config, root instruction files, or any required reference doc is missing or stale, auto-run
/project-init or the narrow lower-level route before ordinary project-specific work. On compaction, resume, delegation, or a context change, re-read the required docs and restate the route before continuing.
- MANDATORY Parent workflow rows do not replace child phase tracking; expand phases and link the parent when nested.
- MANDATORY Orchestrators pre-expand child skill phases before invocation; use
[N.M] /skill-name — phase prefixes and one-in_progress discipline.
Prompt-Enhance Closing Anchors
IMPORTANT MUST ATTENTION follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval
IMPORTANT MUST ATTENTION for every step/sub-skill call: set in_progress before execution, set completed after execution
IMPORTANT MUST ATTENTION every skipped step MUST include explicit reason; every completed step MUST include concise evidence
IMPORTANT MUST ATTENTION if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses
Project Protocol Overlay — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the Target column of the project's skill-protocol index (docs/project-reference/skill-protocols-reference.md by default; a referenceDocs entry in docs/project-config.json overrides the path), taking the most specific matching tier ONLY — exact name > glob > *. That precedence orders overlays against EACH OTHER, never against this skill. Read ONLY the matched bodies, resolved as <protocols-dir>/<Name>.md; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: .claude/skills/project-skill-protocol/references/registry.md.
Overlays are ADDITIVE ONLY: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently.
MUST ATTENTION resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > *, which ranks overlays against each other, NEVER against this skill), read only matched bodies at <protocols-dir>/<Name>.md; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user.
Closing Reminders
IMPORTANT MUST ATTENTION Goal: Force every assumption-laden plan decision and every preservation-critical behavior through explicit user confirmation BEFORE implementation — by interviewing the user with critical questions that validate assumptions and surface issues — so no unstated assumption silently reaches code.
IMPORTANT MUST ATTENTION Main steps: detect plan type → resolve the plan and applicability gate → read plan/phase files → extract decision topics → ask bounded user questions → document confirmed answers → offer implement/refine/skip.
IMPORTANT MUST ATTENTION Applicability: validate the embedded decomposition/slice evidence, explicit roadmap milestone chain, framework technical evidence, or EXEMPT reason/owner plus non-goals, definitions, scenario proof where applicable, skeleton/commands, redacted evidence, and human approval before offering implementation; unresolved intent or evidence is BLOCKED.
Protocols in force (concise digest of the SYNC/shared blocks this skill carries):
- Nested Task Creation: child skill still creates visible phase tasks; link parent when nested.
- Task Tracking & External Report: bootstrap task breakdown first; persist findings incrementally to
plans/reports/.
- Critical Thinking: MUST ATTENTION apply critical + sequential thinking; cite proof; confidence >80% to act.
- Sequential Thinking: structured multi-step Thought N/M with REVISION/BRANCH/HYPOTHESIS markers and confidence closer.
- Project Reference Docs: read required project-reference docs before target work; always include
lessons.md.
- Understand Code First: MUST ATTENTION read code and grep 3+ patterns before any modification.
- Plan Quality: include
## Test Specifications with TC-{FEATURE}-{NNN} IDs per phase.
- Cross-Service Check: scan producers, consumers, sagas, contracts; flag breaking-change risk.
- AI Mistake Prevention: verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity.
IMPORTANT MUST ATTENTION run the main steps IN ORDER — Phase 0 Detect Plan Type → resolve plan path → load mode + questions range → Phase 0.5 Product Readiness / Plan Gate → Step 1 Read plan.md + all phase-*.md (flag decisions/assumptions/risks/tradeoffs) → Step 2 Extract topics (9 categories) → Step 3 Generate questions (2-4 options each) → Step 4 Interview via AskUserQuestion (≤4 per call) → Step 5 Document answers → offer implement/refine/skip — why: the pipeline IS the work; never collapse or skip a step from memory
IMPORTANT MUST ATTENTION validate decisions with the user via AskUserQuestion — NEVER auto-decide or self-answer; completing without ≥1 question is a protocol violation — why: the user owns every assumption-laden choice, not the agent
IMPORTANT MUST ATTENTION detect plan type FIRST (Phase 0) BEFORE generating questions — bugfix keywords (fix, bug, regression, broken, defect) make the Preservation question BLOCKING, never skipped — why: detection drives which categories fire and the Preservation gate
IMPORTANT MUST ATTENTION NEVER modify phase files — persist results by adding ONLY a ## Validation Summary (confirmed decisions + action items) to plan.md — why: phase files are the plan's source of truth and validation is a read-then-annotate pass
- MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using
TaskCreate BEFORE starting (including a task per file read); call TaskList first on context loss, never duplicate — why: resume existing tasks rather than re-plan after compaction
- MANDATORY IMPORTANT MUST ATTENTION honor the
questions MIN-MAX range and mode from ## Plan Context as hard constraints; give 2-4 concrete options per question, never go below min — why: the interview budget is configured, not improvised
- MANDATORY IMPORTANT MUST ATTENTION treat the Preservation "Unsure" answer as BLOCKED → return BLOCKED status and route to
/plan preservation analysis before any implementation — why: an unverified preserved-correctness invariant is a silent regression risk
- MANDATORY IMPORTANT MUST ATTENTION if the plan introduces new tech/packages, probe whether alternatives were evaluated before accepting the choice — why: unevaluated dependency choices raise future change cost
- MANDATORY IMPORTANT MUST ATTENTION cite
file:line proof or traced evidence with confidence % for every claim (>80% act, <80% verify first); admit uncertainty rather than present a guess as fact — why: speculation drives wrong
…(truncated)
1---2name: plan-validate-23description: "[Planning] Use when validating a plan through a critical-questions interview."4---56<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->78> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval.9> **[BLOCKING]** Before each step or sub-skill call, update task tracking: set `in_progress` when step starts, set `completed` when step ends.10> **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason.11> **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.1213<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->1415## Quick Summary1617**Goal:** Force every assumption-laden plan decision and every preservation-critical behavior through explicit user confirmation BEFORE implementation — by interviewing the user with critical questions that validate assumptions and surface issues — so no unstated assumption silently reaches code.1819**Summary:**2021- **Purpose:** validate a finished plan via a critical-questions interview so every assumption-laden decision and every preservation-critical behavior is user-confirmed BEFORE implementation — no unstated assumption silently reaches code.22- **Main steps (run in order):** Phase 0 Detect Plan Type → resolve plan path (`$ARGUMENTS` / `## Plan Context` / ask) → load `mode` + `questions` range as hard constraints → Phase 0.5 resolve Applicability / Plan Gate → Step 1 Read `plan.md` + all `phase-*.md`, flag decisions/assumptions/risks/tradeoffs → Step 2 Extract topics across 9 categories (Applicability, Architecture, Assumptions, Tradeoffs, Risks, Scope, New Tech/Lib, Test Specs, Preservation) → Step 3 Generate questions (2-4 concrete options each, surface implicit decisions) → Step 4 Interview via `AskUserQuestion` (≤4 per call) → Step 5 Document answers → offer implement/refine/skip.23- **Phase 0 weights everything:** plan type (bugfix/feature/migration/refactor/other) decides which question categories fire; any fix/bug/regression/broken/defect keyword makes the Preservation question BLOCKING — never skip it.24- **The output is a REAL interview, not a self-answer:** honor the `questions` MIN-MAX range from `## Plan Context`, give 2-4 concrete options per question, treat the Preservation "Unsure" answer as BLOCKED → route to `/plan`; if the plan adds new tech/packages, probe whether alternatives were evaluated before accepting the choice.25- **Persist results narrowly:** add ONLY a `## Validation Summary` (confirmed decisions + action items) to `plan.md` — NEVER edit phase files; close by offering implement/refine/skip via `AskUserQuestion`.26- **Applicability is mandatory for every plan:** read `.claude/skills/shared/product-roadmap-contract.md`, verify the plan's branch-specific `## Plan Gate`, and ask the owner to confirm the embedded slice/decomposition, explicit roadmap outcome, framework technical outcome, or EXEMPT boundary plus non-goals, scenario proof, commands, evidence, and approval. `BLOCKED`, `OPEN`, `MISSING`, or `REQUIRED` cannot be silently upgraded.2728**Workflow:**29301. **Detect Plan Type** — Classify plan (bugfix/feature/migration/refactor) to weight question categories312. **Read Plan** — Parse plan.md + phase files for decisions, assumptions, risks323. **Extract Topics** — Scan architecture, assumptions, tradeoffs, risks, scope keywords334. **Generate Questions** — Formulate concrete questions with 2-4 options each345. **Interview User** — Present questions using configured count range356. **Document Answers** — Add Validation Summary section to plan.md3637**Key Rules:**3839- MUST ATTENTION use `AskUserQuestion` — NEVER auto-decide on behalf of user — why: the user owns every assumption-laden choice, not the agent40- Ask ONLY about genuine choices affecting implementation — NEVER about non-decision points — why: noise questions burn the interview budget and erode trust41- Bugfix plans ALWAYS trigger the Preservation question (keywords: fix, bug, regression, broken, defect) — why: an unverified preserved-correctness invariant is a silent regression42- Persist via a `## Validation Summary` on `plan.md` — NEVER modify phase files — why: phase files are the plan's source of truth; validation is a read-then-annotate pass43- For embedded, explicit-roadmap, framework/library, or EXEMPT plans, include the final applicability status and exact owning paths in that same summary; use each branch only when the plan records its required evidence and owner.4445## First Principle — Easy to Change4647> **The success metric of every coding decision is _future change cost_.**48> DRY, SRP, abstraction, design patterns, naming, layering, tests — every49> technique exists to serve one goal: **making the next change cheaper**.5051Evaluating code, refactor, test, abstraction, ask:52**does this make next change cheaper or more expensive?**5354- Reject "best practices" raising change cost (premature abstraction,55 speculative generality, leaky indirection, ceremony without payoff).56- Name real enemies in findings: **coupling, hidden state, duplicated57 knowledge, unclear intent, irreversible decisions exposed too early**.58- Simpler design easy to change beats sophisticated design that isn't.5960Apply this lens **before** invoking any specific rule, pattern, or checklist61below — if a downstream rule raises change cost, this principle wins.6263---6465## Phase 0: Detect Plan Type6667Classify plan type BEFORE generating questions — drives question category weighting:6869| Plan Type | Detection | Mandatory Extra Categories |70| ------------- | ----------------------------------------------------------------- | ------------------------------------- |71| **Bugfix** | Title/frontmatter: `fix`, `bug`, `regression`, `broken`, `defect` | Preservation (BLOCKING) |72| **Feature** | New capability, no fix keywords | Architecture, Assumptions, Test Specs |73| **Migration** | Schema change, EF migration, data move | Risks, Preservation, Scope |74| **Refactor** | Restructure/clean up, no behavior change | Preservation, Tradeoffs |75| **Other** | None of above | Architecture, Scope |7677**Bugfix detection is BLOCKING** — NEVER skip Preservation question when fix/bug/regression/broken/defect keywords present.7879## Plan Resolution80811. `$ARGUMENTS` provided → use that path822. Check `## Plan Context` section → use active plan path833. No plan found → ask user to specify path or run `/plan` first8485## Phase 0.5: Applicability / Plan Gate8687Before extracting technical questions, read `.claude/skills/shared/product-roadmap-contract.md` and classify the plan's branch.8889- For an embedded large-idea plan, read the owning PBI/spec and verify the complete `large_idea_decomposition` block, selected slice, non-goals/deferred owners, and conditional scenario artifact when needed. Do not require `docs/product-roadmap.md` or a product milestone.90- For an explicit-roadmap plan, read `docs/product-roadmap.md`, the selected milestone's scope brief, and `scenario-analysis.md`.91- For a framework/library plan, read the technical scope, operational scenarios, generated-carrier evidence, and commands.92- Verify `plan.md` contains one `## Plan Gate` with matching branch/outcome/boundaries, explicit non-goals, defined lifecycle terms when applicable, the branch decision state, known or explicitly inapplicable skeleton/configuration, build/test/run commands, redacted evidence, and `Human approval: APPROVED`.93- Missing upstream artifacts or `BLOCKED`/`OPEN`/`MISSING`/`REQUIRED` values create a blocking Applicability question. Do not begin implementation or recommend `implement` while it remains unresolved.94- For an isolated brownfield change or bugfix, verify the shared contract's EXEMPT branch: the scope brief and plan contain the reason/owner, the sibling scenario exists when required, roadmap/milestone are explicitly `EXEMPT`, product decisions use explicit `N/A` rationale, and commands/evidence/approval are known. Retain all existing preservation/spec/test/review questions.9596## Configuration (from injected context)9798Check `## Plan Context` section:99100- `mode` — auto/prompt/off behavior101- `questions` — range like `3-8` (min-max)102103Use as hard constraints.104105## Workflow106107### Step 1: Read Plan Files108109Read plan directory:110111- `plan.md` — overview + phases list112- `phase-*.md` — all phase files113- Flag: decision points, assumptions, risks, tradeoffs114115### Step 2: Extract Question Topics116117| Category | Keywords |118| ---------------- | ------------------------------------------------------------------------------------------ |119| **Architecture** | approach, pattern, design, structure, database, API |120| **Assumptions** | assume, expect, should, will, must, default |121| **Tradeoffs** | tradeoff, vs, alternative, option, choice, either/or |122| **Risks** | risk, might, could fail, dependency, blocker, concern |123| **Scope** | phase, MVP, future, out of scope, nice to have |124| **New Tech/Lib** | install, add package, new dependency, npm install, dotnet add, unfamiliar framework names |125| **Test Specs** | TC-, test case, coverage, TDD, test specification |126| **Preservation** | auto-trigger on bugfix keywords in title/frontmatter — scan Preservation Inventory section |127| **Product Readiness** | roadmap-applicable or EXEMPT plan — scan the applicable `## Plan Gate` branch, scope/scenario refs, non-goals, definitions, evidence, and human approval |128129### Step 3: Generate Questions130131**Format rules:**132133- 2-4 concrete options per question134- Mark recommended with "(Recommended)" suffix135- "Other" option automatic — do NOT add136- Surface implicit decisions137138For a roadmap-applicable plan, ask a Product Readiness question before lower-level choices:139140> Does the plan implement the owning slice/outcome or technical boundary exactly, with the stated non-goals, lifecycle definitions where applicable, scenario proof, known skeleton/commands, redacted evidence, and human approval?141142Offer concrete choices such as: **Yes, approve the Plan Gate (Recommended)**; **No, revise the scope/plan**; **A product decision remains open**; **This plan is an explicitly accepted isolated-change exemption**. Never answer this question from the plan author's confidence alone.143144**Examples:**145146```147Category: Architecture148Question: "How should validation results be persisted?"149Options:1501. Save to plan.md frontmatter (Recommended) — updates existing plan1512. Create validation-answers.md — separate answers file1523. Don't persist — ephemeral validation only153```154155```156Category: Assumptions157Question: "Plan assumes API rate limiting not needed. Correct?"158Options:1591. Yes, not needed for MVP1602. No, add basic rate limiting now (Recommended)1613. Defer to Phase 2162```163164```165Category: Preservation (MANDATORY when title/frontmatter: fix, bug, regression, broken, defect)166Question: "List 2-3 inputs where CURRENT code is correct. Will fix change behavior on any?"167Options (multi-select):1681. "Current code correct on: {input A}. Fix preserves behavior." (Recommended)1692. "Current code correct on: {input B}. Fix CHANGES behavior because: {justification}"1703. "Current code has NO preserved-correctness inputs — every input was broken" (rare; requires confirmation)1714. "Unsure — need to investigate" (STOP: run /plan preservation analysis)172```173174**Follow-up rules:**175176- Option 2 selected → `plan.md` Preservation Inventory MUST cite Preservation TC asserting new behavior is intended177- Option 4 selected → return BLOCKED status, recommend `/plan` before proceeding178- Option 3 selected → `AskUserQuestion` follow-up: "Confirm: current code has NO preserved invariant? [Yes, every input broken / No, missed some — re-investigate]"179180### Step 4: Interview User181182Use `AskUserQuestion` — NEVER skip or auto-answer.183184**Rules:**185186- Use question count from `## Plan Context` → `Validation: mode=X, questions=MIN-MAX`187- Group related questions (max 4 per tool call)188- Focus: assumptions, risks, tradeoffs, architecture189- MANDATORY IMPORTANT MUST ATTENTION: if plan introduces new tech/packages, ask: "Plan uses {lib}. Were alternatives evaluated? Confirm choice or research more?"190191### Step 5: Document Answers192193Add `## Validation Summary` to `plan.md`:194195```markdown196## Validation Summary197198**Validated:** {date}199**Questions asked:** {count}200201### Applicability202203- **Branch:** DECOMPOSITION-EMBEDDED | EXPLICIT-ROADMAP | FRAMEWORK-LIBRARY | EXEMPT | BLOCKED204- **Owning artifact / roadmap:** `{paths}` or `NOT APPLICABLE — embedded/framework/EXEMPT`205- **Slice / milestone / technical outcome:** `{ID and outcome}`206- **Scope handoff / scenarios:** `{paths or conditional N/A}`207- **Plan Gate:** DECOMPOSITION-EMBEDDED | READY | FRAMEWORK-LIBRARY | EXEMPT | BLOCKED208- **Human approval:** APPROVED | REQUIRED209210### Confirmed Decisions211212- {decision 1}: {user choice}213- {decision 2}: {user choice}214215### Action Items216217- [ ] {changes needed based on answers}218```219220NEVER modify phase files — only document what needs updating.221222## Output223224After validation:225226- Questions asked count227- Key decisions confirmed228- Items flagged for plan revision229- Recommendation: proceed to implementation OR revise plan first230231## Next Steps232233**MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS** after completing, use `AskUserQuestion` to present:234235- **"/feature-implement (Recommended)"** — Begin implementation with validated plan236- **"/refine"** — If plan needs PBI refinement first237- **"Skip, continue manually"** — User decides238239---240241> **[BLOCKING]** MUST ATTENTION use `AskUserQuestion` to interview user. Completing without asking ≥1 question = violation.242243> **[IMPORTANT]** Use `TaskCreate` to break ALL work into small tasks BEFORE starting — including tasks for each file read. For simple tasks, AI MUST ATTENTION ask user whether to skip.244245> **External Memory:** Complex/lengthy work → write findings + results to `plans/reports/` — prevents context loss.246247> **Evidence Gate:** MANDATORY IMPORTANT MUST ATTENTION — every claim requires `file:line` proof or traced evidence with confidence % (>80% act, <80% verify first).248249<!-- SYNC:nested-task-creation -->250251> **Nested Task Expansion Contract** — For workflow-step invocation, the `[Workflow] ...` row is only a parent container; the child skill still creates visible phase tasks.252>253> 1. Call `TaskList` first. If a matching active parent workflow row exists, set `nested=true` and record `parentTaskId`; otherwise run standalone.254> 2. Create one task per declared phase before phase work. When nested, prefix subjects `[N.M] /skill-name — phase`.255> 3. When nested, link the parent with `TaskUpdate(parentTaskId, addBlockedBy: [childIds])`.256> 4. Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.257> 5. Mark exactly one child `in_progress` before work and `completed` immediately after evidence is written.258> 6. Complete the parent only after all child tasks are completed or explicitly cancelled with reason.259>260> **Blocked until:** `TaskList` done, child phases created, parent linked when nested, first child marked `in_progress`.261262<!-- /SYNC:nested-task-creation -->263264<!-- SYNC:task-tracking-external-report -->265266> **Task Tracking & External Report Persistence** — Bootstrap this before execution; then run project-reference doc prefetch before target/source work.267>268> 1. Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first.269> 2. Mark one task `in_progress` before work and `completed` immediately after evidence; never batch transitions.270> 3. For plan/review work, create `plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md` before first finding.271> 4. Append findings after each file/section/decision and synthesize from the report file at the end.272> 5. Final output cites `Full report: plans/reports/{filename}`.273>274> **Blocked until:** task breakdown exists, report path declared for plan/review work, first finding persisted before the next finding.275276<!-- /SYNC:task-tracking-external-report -->277278<!-- SYNC:critical-thinking-mindset -->279280> **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.281> **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.282283<!-- /SYNC:critical-thinking-mindset -->284285<!-- SYNC:sequential-thinking-protocol -->286287> **Sequential Thinking Protocol** — Structured multi-step reasoning for complex/ambiguous work. Use when planning, reviewing, debugging, or refining ideas where one-shot reasoning is unsafe.288>289> **Trigger when:** complex problem decomposition · adaptive plans needing revision · analysis with course correction · unclear/emerging scope · multi-step solutions · hypothesis-driven debugging · cross-cutting trade-off evaluation.290>291> **Format (explicit mode — visible thought trail):**292>293> 1. `Thought N/M: [aspect]` — one aspect per thought, state assumptions/uncertainty294> 2. `Thought N/M [REVISION of Thought K]: ...` — when prior reasoning invalidated; state Original / Why revised / Impact295> 3. `Thought N/M [BRANCH A from Thought K]: ...` — explore alternative; converge with decision rationale296> 4. `Thought N/M [HYPOTHESIS]: ...` then `[VERIFICATION]: ...` — test before acting297> 5. `Thought N/N [FINAL]` — only when verified, all critical aspects addressed, confidence >80%298>299> **Mandatory closers:** Confidence % stated · Assumptions listed · Open questions surfaced · Next action concrete.300>301> **Stop conditions:** confidence <80% on any critical decision → escalate via AskUserQuestion · ≥3 revisions on same thought → re-frame the problem · branch count >3 → split into sub-task.302>303> **Implicit mode:** apply methodology internally without visible markers when adding markers would clutter the response (routine work where reasoning aids accuracy).304>305> **Deep-dive:** see `/sequential-thinking` skill (`.claude/skills/sequential-thinking/SKILL.md`) for worked examples (API design, debugging, architecture), advanced techniques (spiral refinement, hypothesis testing, convergence), and meta-strategies (uncertainty handling, revision cascades).306307<!-- /SYNC:sequential-thinking-protocol -->308309<!-- SYNC:project-reference-docs-guide -->310311> **Project Reference Docs Gate (static JIT)** — Run after task-tracking bootstrap and immediately before target/source file reads, grep, edits, tests, or analysis. Project docs override generic framework assumptions; hooks may remind or accelerate this gate, but never prove that it ran.312>313> 1. Identify scope: file types, domain area, and operation.314> 2. **Read `docs/project-config.json` first — the project's machine-readable map.** It is the single source of truth for THIS repo (modules/paths, framework + search keywords, test/E2E/integration run-commands, design system, architecture rules, workflow patterns); ground exact paths, run-commands, and conventions on it **before investigating, planning, or coding** — never assume framework defaults (`CLAUDE.md` + reference docs are derived from it). If it — or the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any required reference doc — is missing or stale, auto-run `/project-init` or the narrow route (`/project-config`, `/docs-init`, `/scan-all`, `/scan --target=<key>`, `/claude-md-init`) first; if Codex mirrors or `AGENTS.md` are stale, ask the user to run `/sync-codex` (never auto-run it).315> 3. Required docs by trigger: always `docs/project-reference/lessons.md`; doc lookup `docs-index-reference.md`; review `code-review-rules.md`; backend/CQRS/API `backend-patterns-reference.md`; domain/entity `domain-entities-reference.md`; frontend/UI `frontend-patterns-reference.md`; styles/design `scss-styling-guide.md` + `design-system/design-system-canonical.md`; integration tests `integration-test-reference.md`; E2E `e2e-test-reference.md`; feature docs/specs `feature-spec-reference.md` + `spec-system-reference.md` + `spec-principles.md`; behavior/public-contract/spec-test-code sync `workflow-spec-test-code-cycle-reference.md`; derived spec index/ERD/reimplementation guides `spec-system-reference.md` + source Feature Specs under `docs/specs/`; architecture/new area `project-structure-reference.md`.316> 4. Read every required doc, then before target work state: `Reference docs read: ... | Not applicable: ...`. After compaction, resume, delegation, or a material context change, repeat the route and restate the set; prior conversation and hook output are not proof of current loading.317>318> **Ready when:** scope evaluated, `docs/project-config.json` consulted, required docs checked/read or setup route completed, `lessons.md` confirmed, citation emitted.319320<!-- /SYNC:project-reference-docs-guide -->321322<!-- SYNC:understand-code-first -->323324> **Understand Code First** — HARD-GATE: Do NOT write, plan, or fix until you READ existing code.325>326> 1. Search 3+ similar patterns (`grep`/`glob`) — cite `file:line` evidence327> 2. Read existing files in target area — understand structure, base classes, conventions328> 3. Run `python .claude/scripts/code_graph trace <file> --direction both --json` when `.code-graph/graph.db` exists329> 4. Map dependencies via `connections` or `callers_of` — know what depends on your target330> 5. Write investigation to `.ai/workspace/analysis/` for non-trivial tasks (3+ files)331> 6. Re-read analysis file before implementing — never work from memory alone. — why: long context drifts from the file; the file is ground truth332> 7. NEVER invent new patterns when existing ones work — match exactly or document deviation. — why: divergent patterns fragment the codebase and slow every future reader333>334> **BLOCKED until:** `- [ ]` Read target files `- [ ]` Grep 3+ patterns `- [ ]` Graph trace (if graph.db exists) `- [ ]` Assumptions verified with evidence335336<!-- /SYNC:understand-code-first -->337338<!-- SYNC:plan-quality -->339340> **Plan Quality** — Every plan phase MUST ATTENTION include test specifications.341>342> 1. Add `## Test Specifications` section with TC-{FEATURE}-{NNN} IDs to every phase file343> 2. Map every functional requirement to ≥1 TC (or explicit `TBD` with rationale)344> 3. TC IDs follow `TC-{FEATURE}-{NNN}` format — reference by ID, never embed full content345> 4. Before any new workflow step: call `TaskList` and re-read the phase file346> 5. On context compaction: call `TaskList` FIRST — never create duplicate tasks347> 6. Verify TC satisfaction per phase before marking complete (evidence must be `file:line`, not TBD)348> 7. **Purpose-oriented naming:** For every planned public or cross-layer contract, port, interface, module, or adapter, name the consumer-visible capability or domain purpose; keep provider, framework, and transport names in concrete implementations (`IStorage`/`Storage` → `AzureBlobStorage`). — why: a contract name should survive an implementation swap.349> 8. **Contract-fit gate:** Check the proposed name against its callers and all implementations; use a narrower purpose name when a broad name overpromises (`IObjectStore` or `DocumentStore` instead of `IStorage` when the behavior is narrower). — why: abstraction names must describe the actual contract, not hide a mismatch.350> 9. **No speculative abstraction:** Plan an interface or port only when a real boundary, substitution need, or multiple meaningful implementations justifies it; keep a concrete type when it is the honest contract. — why: an unnecessary abstraction adds indirection and a second name without reducing change cost.351> 10. **Language convention:** Preserve the repository's naming syntax (`I` prefix where the language/project uses it); never force `I` or `Interface` markers across languages. — why: semantic purpose is portable, syntax is not.352> 11. **Foundation obligations — when the plan CREATES or CHANGES how the project is built, run, tested, or checked** (build or CI configuration, test harness, containerization, toolchain/dependency management, module boundaries, quality tooling): run `SYNC:engineering-foundation-gate` — its seven dimensions F1-F7, the four profile axes and the warranting matrix are in `.claude/docs/engineering-foundation-catalog.md`, which the plan reads directly when no carrier of that gate ran upstream — and carry every dimension it marks warranted into the plan as an **explicit phase with acceptance criteria** — never as an assumption that someone handles it later. Record each dimension deliberately skipped, with the reason. — why: a plan that stands up a foundation and silently omits a warranted dimension makes that omission permanent and invisible; foundations cost near nothing at creation and a great deal to retrofit.353>354> **Mode:** TDD-first → reference existing TCs with `Evidence: TBD`. Implement-first → use TBD → `/spec [mode=tests]` fills after.355356<!-- /SYNC:plan-quality -->357358<!-- SYNC:cross-service-check -->359360> **Cross-Service Check** — Microservices/event-driven: MANDATORY before concluding investigation, plan, spec, or feature doc. Missing downstream consumer = silent regression.361>362> | Boundary | Grep terms |363> | ------------------- | ------------------------------------------------------------------------------- |364> | Event producers | `Publish`, `Dispatch`, `Send`, `emit`, `EventBus`, `outbox`, `IntegrationEvent` |365> | Event consumers | `Consumer`, `EventHandler`, `Subscribe`, `@EventListener`, `inbox` |366> | Sagas/orchestration | `Saga`, `ProcessManager`, `Choreography`, `Workflow`, `Orchestrator` |367> | Sync service calls | HTTP/gRPC calls to/from other services |368> | Shared contracts | OpenAPI spec, proto, shared DTO — flag breaking changes |369> | Data ownership | Other service reads/writes same table/collection → Shared-DB anti-pattern |370>371> **Per touchpoint:** owner service · message name · consumers · risk (NONE / ADDITIVE / BREAKING).372>373> **BLOCKED until:** Producers scanned · Consumers scanned · Sagas checked · Contracts reviewed · Breaking-change risk flagged374375<!-- /SYNC:cross-service-check -->376377<!-- SYNC:ai-mistake-prevention -->378379> **AI Mistake Prevention** — Failure modes to avoid on every task:380>381> **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting.382> **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing.383> **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first.384> **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done.385> **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect.386> **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard.387> **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk.388> **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure.389> **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.390391<!-- /SYNC:ai-mistake-prevention -->392393<!-- SYNC:understand-code-first:reminder -->394395**IMPORTANT MUST ATTENTION** search 3+ existing patterns and read code BEFORE any modification. Run graph trace when graph.db exists.396397<!-- /SYNC:understand-code-first:reminder -->398399<!-- SYNC:evidence-based-reasoning:reminder -->400401- **MANDATORY IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim. Confidence >80% to act, <60% = do NOT recommend.402<!-- /SYNC:evidence-based-reasoning:reminder -->403404<!-- SYNC:plan-quality:reminder -->405406**IMPORTANT MUST ATTENTION** include `## Test Specifications` with TC IDs per phase. Call `TaskList` before creating new tasks.407408<!-- /SYNC:plan-quality:reminder -->409410<!-- SYNC:cross-service-check:reminder -->411412**IMPORTANT MUST ATTENTION** microservices/event-driven: scan producers, consumers, sagas, contracts in task scope. Per touchpoint: owner · message · consumers · risk (NONE/ADDITIVE/BREAKING). Missing consumer = silent regression.413414<!-- /SYNC:cross-service-check:reminder -->415416<!-- SYNC:critical-thinking-mindset:reminder -->417418**MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence.419420<!-- /SYNC:critical-thinking-mindset:reminder -->421422<!-- SYNC:sequential-thinking-protocol:reminder -->423424**MUST ATTENTION** apply sequential-thinking — multi-step Thought N/M, REVISION/BRANCH/HYPOTHESIS markers, confidence % closer; see `/sequential-thinking` skill.425426<!-- /SYNC:sequential-thinking-protocol:reminder -->427428<!-- SYNC:ai-mistake-prevention:reminder -->429430**MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting.431432<!-- /SYNC:ai-mistake-prevention:reminder -->433434<!-- SYNC:task-tracking-external-report:reminder -->435436- **MANDATORY** Bootstrap task tracking before target work; transition one task at a time.437- **MANDATORY** Persist plan/review findings to `plans/reports/` incrementally and synthesize from disk.438439<!-- /SYNC:task-tracking-external-report:reminder -->440441<!-- SYNC:project-reference-docs-guide:reminder -->442443- **MANDATORY** Before investigating, planning, or coding, read `docs/project-config.json` (the project map: modules/paths, run-commands, conventions, architecture/workflow rules) + the required project-reference docs, and cite `Reference docs read: ...`.444- **MANDATORY** Load detail just in time immediately before the first target read/grep/edit/test; hooks may provide a pointer, but a hook event or prior turn is never evidence that the current files were read.445- **MANDATORY** Always include `lessons.md`; project config + conventions override generic framework defaults.446- **MANDATORY** If project config, root instruction files, or any required reference doc is missing or stale, auto-run `/project-init` or the narrow lower-level route before ordinary project-specific work. On compaction, resume, delegation, or a context change, re-read the required docs and restate the route before continuing.447448<!-- /SYNC:project-reference-docs-guide:reminder -->449450<!-- SYNC:nested-task-creation:reminder -->451452- **MANDATORY** Parent workflow rows do not replace child phase tracking; expand phases and link the parent when nested.453- **MANDATORY** Orchestrators pre-expand child skill phases before invocation; use `[N.M] /skill-name — phase` prefixes and one-`in_progress` discipline.454455<!-- /SYNC:nested-task-creation:reminder -->456457<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:START -->458459## Prompt-Enhance Closing Anchors460461**IMPORTANT MUST ATTENTION** follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval462**IMPORTANT MUST ATTENTION** for every step/sub-skill call: set `in_progress` before execution, set `completed` after execution463**IMPORTANT MUST ATTENTION** every skipped step MUST include explicit reason; every completed step MUST include concise evidence464**IMPORTANT MUST ATTENTION** if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses465466<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:END -->467468<!-- SYNC:project-protocol-overlay -->469470> **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `<protocols-dir>/<Name>.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`.471>472> Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently.473474<!-- /SYNC:project-protocol-overlay -->475476<!-- SYNC:project-protocol-overlay:reminder -->477478**MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `<protocols-dir>/<Name>.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user.479480<!-- /SYNC:project-protocol-overlay:reminder -->481482## Closing Reminders483484**IMPORTANT MUST ATTENTION Goal:** Force every assumption-laden plan decision and every preservation-critical behavior through explicit user confirmation BEFORE implementation — by interviewing the user with critical questions that validate assumptions and surface issues — so no unstated assumption silently reaches code.485486**IMPORTANT MUST ATTENTION Main steps:** detect plan type → resolve the plan and applicability gate → read plan/phase files → extract decision topics → ask bounded user questions → document confirmed answers → offer implement/refine/skip.487488**IMPORTANT MUST ATTENTION Applicability:** validate the embedded decomposition/slice evidence, explicit roadmap milestone chain, framework technical evidence, or EXEMPT reason/owner plus non-goals, definitions, scenario proof where applicable, skeleton/commands, redacted evidence, and human approval before offering implementation; unresolved intent or evidence is BLOCKED.489490**Protocols in force (concise digest of the SYNC/shared blocks this skill carries):**491492- **Nested Task Creation:** child skill still creates visible phase tasks; link parent when nested.493- **Task Tracking & External Report:** bootstrap task breakdown first; persist findings incrementally to `plans/reports/`.494- **Critical Thinking:** MUST ATTENTION apply critical + sequential thinking; cite proof; confidence >80% to act.495- **Sequential Thinking:** structured multi-step Thought N/M with REVISION/BRANCH/HYPOTHESIS markers and confidence closer.496- **Project Reference Docs:** read required project-reference docs before target work; always include `lessons.md`.497- **Understand Code First:** MUST ATTENTION read code and grep 3+ patterns before any modification.498- **Plan Quality:** include `## Test Specifications` with TC-{FEATURE}-{NNN} IDs per phase.499- **Cross-Service Check:** scan producers, consumers, sagas, contracts; flag breaking-change risk.500- **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity.501502**IMPORTANT MUST ATTENTION** run the main steps IN ORDER — Phase 0 Detect Plan Type → resolve plan path → load `mode` + `questions` range → Phase 0.5 Product Readiness / Plan Gate → Step 1 Read `plan.md` + all `phase-*.md` (flag decisions/assumptions/risks/tradeoffs) → Step 2 Extract topics (9 categories) → Step 3 Generate questions (2-4 options each) → Step 4 Interview via `AskUserQuestion` (≤4 per call) → Step 5 Document answers → offer implement/refine/skip — why: the pipeline IS the work; never collapse or skip a step from memory503504**IMPORTANT MUST ATTENTION** validate decisions with the user via `AskUserQuestion` — NEVER auto-decide or self-answer; completing without ≥1 question is a protocol violation — why: the user owns every assumption-laden choice, not the agent505**IMPORTANT MUST ATTENTION** detect plan type FIRST (Phase 0) BEFORE generating questions — bugfix keywords (fix, bug, regression, broken, defect) make the Preservation question BLOCKING, never skipped — why: detection drives which categories fire and the Preservation gate506**IMPORTANT MUST ATTENTION** NEVER modify phase files — persist results by adding ONLY a `## Validation Summary` (confirmed decisions + action items) to `plan.md` — why: phase files are the plan's source of truth and validation is a read-then-annotate pass507508- **MANDATORY IMPORTANT MUST ATTENTION** break work into small todo tasks using `TaskCreate` BEFORE starting (including a task per file read); call `TaskList` first on context loss, never duplicate — why: resume existing tasks rather than re-plan after compaction509- **MANDATORY IMPORTANT MUST ATTENTION** honor the `questions` MIN-MAX range and `mode` from `## Plan Context` as hard constraints; give 2-4 concrete options per question, never go below min — why: the interview budget is configured, not improvised510- **MANDATORY IMPORTANT MUST ATTENTION** treat the Preservation "Unsure" answer as BLOCKED → return BLOCKED status and route to `/plan` preservation analysis before any implementation — why: an unverified preserved-correctness invariant is a silent regression risk511- **MANDATORY IMPORTANT MUST ATTENTION** if the plan introduces new tech/packages, probe whether alternatives were evaluated before accepting the choice — why: unevaluated dependency choices raise future change cost512- **MANDATORY IMPORTANT MUST ATTENTION** cite `file:line` proof or traced evidence with confidence % for every claim (>80% act, <80% verify first); admit uncertainty rather than present a guess as fact — why: speculation drives wrong 513514…(truncated)