# Feature Implement > [Implementation] Use when you need to implement a feature [step by step]. - Skill: `duc01226/feature-implement` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/feature-implement` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/feature-implement/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/duc01226/feature-implement --- > Codex compatibility note: > > - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references. > - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes. > - User-question prompts mean to ask the user directly in Codex. > - Ignore Claude-specific mode-switch instructions when they appear. > - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written. > - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task. > - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first. > - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence. > - If a required step/tool cannot run in this environment, stop and ask the user before adapting. ## Codex Project-Reference Loading (No Hooks) Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing. **Always read:** - `docs/project-config.json` (project-specific paths, commands, modules, and workflow/test settings) - `docs/project-reference/docs-index-reference.md` (routes to the full `docs/project-reference/*` catalog) - `docs/project-reference/lessons.md` (always-on guardrails and anti-patterns) **Missing/stale context route:** If `docs/project-config.json`, the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any task-required reference doc is missing or stale, auto-run `$project-init` or the narrow setup route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=`, `$claude-md-init`) before ordinary project-specific work. If Codex mirrors or `AGENTS.md` are missing/stale, ask the user to run `$sync-codex`; do not auto-run it. **Situation-based docs:** - Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): `project-structure-reference.md` - Backend/CQRS/API/domain/entity changes: `backend-patterns-reference.md`, `domain-entities-reference.md` - Frontend/UI/styling/design-system: `frontend-patterns-reference.md`, `scss-styling-guide.md`, `design-system/README.md` - Spec authoring, `docs/specs/` pathing, or TC format: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md` - Behavior/public-contract changes or spec-test-code sync: `workflow-spec-test-code-cycle-reference.md` plus the spec docs above - Derived spec indexes/ERDs/reimplementation guides: `spec-system-reference.md` and source Feature Specs under `docs/specs/` - Integration test implementation/review: `integration-test-reference.md` - E2E test implementation/review: `e2e-test-reference.md` - Code review/audit work: `code-review-rules.md` plus domain docs above based on changed files Do not read all docs blindly. Start from `docs-index-reference.md`, then open only relevant files for the task. > **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, merge steps without explicit user approval. > **[BLOCKING]** Before each step or sub-skill call, update task tracking: `in_progress` on start, `completed` on end. > **[BLOCKING]** Every completed/skipped step MUST include evidence or explicit skip reason. > **[BLOCKING]** If Task tools unavailable, maintain equivalent step-by-step plan tracker with same status transitions. ## Quick Summary **Goal:** Ship a correct, fully-verified feature that satisfies the saved Goal Contract — implemented with deep research, comprehensive planning, and maximum quality verification (planned, reviewed, tested, documented) — with no skipped quality gate on any non-trivial change. **Workflow:** 1. **Research** — Deep investigation, multiple researcher subagents 2. **Plan** — Detailed plan via `$plan`; user approval required 3. **Implement** — Execute with full code review + SRE review 4. **Verify** — Run all tests, review changes, update docs **Key Rules:** - Maximum thoroughness: research → plan → implement → review → test → docs - User approval required at plan stage - Break work into todo tasks; add final self-review task > **Renamed:** formerly `cook` — now `$feature-implement`. The old name no longer resolves as a slash command. > **feature-implement vs plan-execute:** `feature-implement` takes an idea/feature description and goes idea → research → **plan (created here)** → shipped. Use `$plan-execute` instead when a plan file already exists and you only need disciplined phase-by-phase execution + commit. feature-implement owns the front of the pipeline (research + planning); plan-execute owns the back (phase gates + auto-commit + `--parallel`/`--approval`/`--tests` flags). ## Standalone Mode Pipeline (skip entirely if invoked inside a workflow) > **MANDATORY — standalone `$feature-implement` only.** When invoked OUTSIDE a workflow, wrap the core spine in this quality loop. Detect an active workflow via the current task list FIRST: if a parent `[Workflow]` row exists, SKIP this section — the surrounding workflow already sequences plan/review/why-review around this skill (e.g. `workflow-feature` wraps feature-implement with exactly these steps). > > Create these as task tracking tasks up front, in order, then execute them: > > 1. **`$spec` — spec-driven, BEFORE any plan or code.** Create or update the tech-free 8-section Feature Spec under `docs/specs/` so the plan and implementation satisfy an agreed contract, not chat memory. Decide the case from evidence: net-new capability with no code yet → `$spec [mode=draft]` (provisional, `Evidence: TBD`); enhancement to an already-documented feature → `$spec [mode=update]`; behavior/contract change to existing spec → `$spec [mode=amend]`; buggy/undocumented area that now warrants a spec → `$spec [mode=init]`. If a governing spec already exists and fully covers this change, record `Spec verified current — no change` with `file:line` evidence and proceed. **Skip ONLY in fast mode** (ALL Default Mode Policy trivial-task conditions met — no behavior/contract change); record the skip reason. Decide the case explicitly — skip only the authoring, never the decision. > 2. **`$plan`** — author the implementation plan from the spec. feature-implement's Comprehensive Planning phase (Step 2) satisfies this; emit a reviewable plan artifact under `plans/`. Map each plan phase's `## Test Specifications` to the spec's §8 `TC-{FEATURE}-{NNN}` IDs. > 3. **`$plan-review`** — recursively review/validate the plan; fix validated findings before implementing. > 4. **Proceed** — execute the core implementation spine (research already done → implement → test → review → docs). > 5. **`$spec [mode=sync]`** — _spec-driven closure._ Reconcile the spec's §8 `TC-{FEATURE}-{NNN}` ↔ integration tests and refresh `Evidence: TBD` markers to real `file:line` now that code exists. Run `$spec [mode=tests]` first if the implementation introduced behavior not yet captured as a test case. Skip only when step 1 was skipped (fast-mode trivial, no spec touched). > 6. **`$changes-review`** — review the diff before commit. > 7. **`$why-review`** — review rationale and change quality of the implementation. ## 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**. When evaluating code, refactor, test, or abstraction, ask: **does this make the 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 would raise change cost, this principle wins. --- ## Default Mode Policy > **Default mode HARD (full rigor).** Every section below — deep research, mandatory `$plan`, full `code-reviewer` review, mandatory tests, mandatory `$docs-update` — applies by default. > > **Opt out to fast mode ONLY when ALL true** (task genuinely trivial): > > - Single-file edit, ≤30 lines changed > - No design choice (only one reasonable approach) > - No cross-service impact, no contract change, no new dependency > - No new pattern — follows existing codebase pattern > - Existing tests cover change OR change non-functional (typo, comment, log message) > > **Any condition fails → use full protocol below.** When in doubt, default hard. Skipping review/tests on non-trivial change ships bugs. > > **Fast mode skips (and only skips):** researcher subagent phase (direct grep instead), mandatory `code-reviewer` review (self-review only), separate test phase (verify inline). Does NOT skip `$plan` step, test execution, `$docs-update` triage. ### Backend Context (if applicable) > When task involves backend changes, read these directly before implementing: - CQRS commands/queries, validation, repositories, entity events: `docs/project-reference/backend-patterns-reference.md` - Entity catalog, relationships, cross-service sync: `docs/project-reference/domain-entities-reference.md` - **Repository type (service-specific):** when the project declares a per-service repository abstraction (`backendServices.serviceRepositories` in `docs/project-config.json`), use that repository type for the service — NEVER the generic root repository base. ### Frontend/UI Context (if applicable) > When task involves frontend or UI changes: - Component patterns: `docs/project-reference/frontend-patterns-reference.md` - Styling/BEM guide: `docs/project-reference/scss-styling-guide.md` - Design system tokens: `docs/project-reference/design-system/README.md` **Ultrathink** plan and implement these tasks with maximum verification: **Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.** $ARGUMENTS **Mode:** Extra research, detailed planning, mandatory reviews. ## Workflow ### 0. Goal Contract Read (BEFORE implementation) - Resolve the active Goal Contract per `SYNC:goal-contract-satisfaction-loop`: active plan `goal.md` → `plans/goals/{YYMMDD-HHmm}-{slug}/goal.md` → create from the current request via `.claude/templates/goal-contract-template.md`. - Read the saved success criteria BEFORE any code change — implementation serves the saved criteria, not chat memory. - After implementation and verification, append an Iteration Log entry to the goal file: result, evidence references (`file:line`, command output), remaining gaps mapped to criteria. ### 1. Deep Research Phase - Launch 2-3 `researcher` subagents in parallel covering: - Technical approach validation - Edge cases, failure modes - Security implications - Performance considerations - Use `$scout --ext` for comprehensive codebase analysis - Research reports max 150 lines each - **External Memory:** Write all research to `.ai/workspace/analysis/{task-name}.analysis.md`. Re-read ENTIRE file before planning. - **Pre-Implementation Trace Gate:** For bugfix, failed verification, stale/incorrect final output, regression, or behavior-changing fix plans, MUST ATTENTION confirm the plan/referenced analysis includes `Debugger Trace: End -> Start`, all feeder paths, hypothesis matrix, owning fix layer, and forward convergence proof. If missing, STOP and produce the missing-trace list before editing. > After implementing, run `python .claude/scripts/code_graph connections --json` on modified files; verify no related files need updates. ### Graph-Trace Before Implementation When graph DB available, BEFORE writing code, trace blast radius: - `python .claude/scripts/code_graph trace --direction both --json` — what calls this code AND what it triggers - `python .claude/scripts/code_graph trace --direction downstream --json` — all downstream consumers - Prevents breaking implicit dependencies (bus message consumers, event handlers) ### 2. Comprehensive Planning - Use `planner` subagent with all research reports - Create full plan directory: - `plan.md` — overview with risk assessment - `phase-XX-*.md` — detailed phase files - Success criteria per phase - Rollback strategy ### 3. Verified Implementation - Implement one phase at a time - After each phase: - Run type-check, compile - Run relevant tests - Self-review before proceeding ### Batch Checkpoint (Large Plans) For plans with 10+ tasks, execute in batches with human review: 1. **Execute batch** — Complete next 3 tasks (or user-specified size) 2. **Report** — Show implementation, verification output, any concerns 3. **Wait** — Say "Ready for feedback" and STOP. Do NOT continue automatically. 4. **Apply feedback** — Incorporate changes, execute next batch 5. **Repeat** until all tasks complete Plans with 10+ tasks — do NOT execute all tasks continuously without checkpoint. Stop after every batch for human review. Prevents runaway execution where early mistakes compound through later tasks. ### 4. Mandatory Testing - Use `tester` subagent for full test coverage - Write tests for: - Happy path scenarios - Edge cases from research - Error handling paths - NO mocks or fake data - Repeat until all tests pass ### 5. Mandatory Code Review - Use `code-reviewer` subagent - Address all critical and major findings - Re-run tests after fixes - Repeat until approved ### 6. Documentation Update - Use `docs-manager` to update relevant docs - Use `project-manager` to update project status - Record architectural decisions ### 7. Final Report - Summary of all changes - Test coverage metrics - Security considerations addressed - Unresolved questions (if any) - Ask user to review and approve ## When to Use - Critical production features - Security-sensitive changes - Public API modifications - Database schema changes - Cross-service integrations ## Quality Gates | Gate | Criteria | | -------- | ------------------------- | | Research | 2+ researcher reports | | Planning | Full plan directory | | Tests | All pass, no mocks | | Review | 0 critical/major findings | | Docs | Updated if needed | --- ## Next Steps (Standalone: MUST ATTENTION ask user by asking the user directly. Skip if inside workflow.) > **MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS:** If this skill was called **outside a workflow**, MUST ATTENTION use ask the user directly to present these options. Do NOT skip because task seems "simple" or "obvious" — user decides: - **"Proceed with full workflow (Recommended)"** — Detect best workflow to continue from here (feature implemented). Ensures review, testing, docs steps aren't skipped. - **"$code-simplifier"** — Simplify and clean up implementation - **"$workflow-review-changes"** — Review changes before commit - **"Skip, continue manually"** — user decides > If already inside a workflow, skip — workflow handles sequencing. > **[IMPORTANT]** Use task tracking to break ALL work into small tasks BEFORE starting — including tasks for each file read. Prevents context loss from long files. For simple tasks, MUST ATTENTION ask user whether to skip. - `docs/project-reference/domain-entities-reference.md` — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models) - `docs/specs/` — Test specifications by module (read existing TCs; generate/update via `$spec [mode=tests]` after implementation) > **End-to-Start Debugger Trace** — For non-trivial bugs, failed verification, regression fixes, behavior-changing code, or unclear code flow, start from the observed final state and walk backward before proposing a fix. > > 1. **Frame 0: observed end state** — Name the exact user-visible output, failing assertion, log line, persisted value, API response, rendered UI, or aggregate bucket. Record the reader/query/renderer that produced it with `file:line` evidence. > 2. **Walk backward one hop at a time** — Trace final reader -> projection/cache/storage -> writer -> consumer/handler/job -> producer/caller -> original trigger. At every hop record: input, transformation, output, owner, and evidence. > 3. **Enumerate all feeder paths** — Find every upstream producer/caller/event/job that can write into the final path, including retry, async, cache, background, and alternate UI/API paths. Mark each path verified, ruled out, or still unknown. > 4. **Build the hypothesis matrix** — For each plausible cause, list evidence for, evidence against, how to reproduce/verify, blast radius, and status (`primary`, `contributing`, `ruled out`, `latent`). Do not fix until competing causes are explicitly resolved or bounded. > 5. **Choose the owning fix layer** — Identify the invariant owner and the lowest shared point that protects all downstream consumers. A fix at the symptom site is rejected unless the symptom site owns the invariant. > 6. **Prove convergence forward** — After choosing the fix, walk start -> end again and show how the corrected state reaches the observed final output. Map each root cause to a fix part and each fix part to a test/proof. > > **BLOCKED until:** final state named · backward trace written · all feeder paths enumerated · hypothesis matrix completed · owning fix layer justified · forward convergence proof mapped to tests. > > **NEVER:** Start at the first suspicious code path. Collapse multiple producers into one "flow". Treat duplicate symptoms as duplicate records without proving the read model. Skip ruled-out hypotheses. > **Source/test drift check.** For coding, fix, debug, investigation, test, or review work: when source behavior changes, inspect affected unit/integration/E2E tests and decide from evidence whether tests should change to match intended behavior or the source change is an unintended bug to fix. Do not write tests for migration code; schema/data migrations are one-time execution paths, not core application logic. > **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. > **UI System Context** — For ANY task touching `.ts`, `.html`, `.scss`, or `.css` files: > > **MUST ATTENTION READ before implementing:** > > 1. `docs/project-reference/frontend-patterns-reference.md` — component base classes, stores, forms > 2. `docs/project-reference/scss-styling-guide.md` — BEM methodology, SCSS variables, mixins, responsive > 3. `docs/project-reference/design-system/README.md` — design tokens, component inventory, icons > > Reference `docs/project-config.json` for project-specific paths. > **Graph-Assisted Investigation** — MANDATORY when `.code-graph/graph.db` exists. > > **HARD-GATE:** MUST ATTENTION run at least ONE graph command on key files before concluding any investigation. > > **Pattern:** Grep finds files → `trace --direction both` reveals full system flow → Grep verifies details > > | Task | Minimum Graph Action | > | ------------------- | -------------------------------------------- | > | Investigation/Scout | `trace --direction both` on 2-3 entry files | > | Fix/Debug | `callers_of` on buggy function + `tests_for` | > | Feature/Enhancement | `connections` on files to be modified | > | Code Review | `tests_for` on changed functions | > | Blast Radius | `trace --direction downstream` | > > **CLI:** `python .claude/scripts/code_graph {command} --json`. Use `--node-mode file` first (10-30x less noise), then `--node-mode function` for detail. > **Nested Task Expansion Contract** — For workflow-step invocation, the `[Workflow] ...` row is only a parent container; the child skill still creates visible phase tasks. > > 1. Call the current task list first. If a matching active parent workflow row exists, set `nested=true` and record `parentTaskId`; otherwise run standalone. > 2. Create one task per declared phase before phase work. When nested, prefix subjects `[N.M] $skill-name — phase`. > 3. When nested, link the parent with `TaskUpdate(parentTaskId, addBlockedBy: [childIds])`. > 4. Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent. > 5. Mark exactly one child `in_progress` before work and `completed` immediately after evidence is written. > 6. Complete the parent only after all child tasks are completed or explicitly cancelled with reason. > > **Blocked until:** the current task list done, child phases created, parent linked when nested, first child marked `in_progress`. > **Project Reference Docs Gate** — Run after task-tracking bootstrap and before target/source file reads, grep, edits, or analysis. Project docs override generic framework assumptions. > > 1. Identify scope: file types, domain area, and operation. > 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=`, `$claude-md-init`) first; if Codex mirrors or `AGENTS.md` are stale, ask the user to run `$sync-codex` (never auto-run it). > 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`. > 4. Read every required doc, then before target work state: `Reference docs read: ... | Not applicable: ...`. > > **Ready when:** scope evaluated, `docs/project-config.json` consulted, required docs checked/read or setup route completed, `lessons.md` confirmed, citation emitted. > **Task Tracking & External Report Persistence** — Bootstrap this before execution; then run project-reference doc prefetch before target/source work. > > 1. Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first. > 2. Mark one task `in_progress` before work and `completed` immediately after evidence; never batch transitions. > 3. For plan/review work, create `plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md` before first finding. > 4. Append findings after each file/section/decision and synthesize from the report file at the end. > 5. 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. > **Understand Code First** — HARD-GATE: Do NOT write, plan, or fix until you READ existing code. > > 1. Search 3+ similar patterns (`grep`/`glob`) — cite `file:line` evidence > 2. Read existing files in target area — understand structure, base classes, conventions > 3. Run `python .claude/scripts/code_graph trace --direction both --json` when `.code-graph/graph.db` exists > 4. Map dependencies via `connections` or `callers_of` — know what depends on your target > 5. Write investigation to `.ai/workspace/analysis/` for non-trivial tasks (3+ files) > 6. Re-read analysis file before implementing — never work from memory alone. — why: long context drifts from the file; the file is ground truth > 7. 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. > > 1. Add `## Test Specifications` section with TC-{FEATURE}-{NNN} IDs to every phase file > 2. Map every functional requirement to ≥1 TC (or explicit `TBD` with rationale) > 3. TC IDs follow `TC-{FEATURE}-{NNN}` format — reference by ID, never embed full content > 4. Before any new workflow step: call the current task list and re-read the phase file > 5. On context compaction: call the current task list FIRST — never create duplicate tasks > 6. Verify TC satisfaction per phase before marking complete (evidence must be `file:line`, not TBD) > > **Mode:** TDD-first → reference existing TCs with `Evidence: TBD`. Implement-first → use TBD → `$spec [mode=tests]` fills after. - **MANDATORY 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. - **MANDATORY IMPORTANT MUST ATTENTION** include `## Test Specifications` with TC IDs per phase. Call the current task list before creating new tasks. - **MANDATORY IMPORTANT MUST ATTENTION** read frontend-patterns-reference, scss-styling-guide, design-system/README before any UI change. - **MANDATORY IMPORTANT MUST ATTENTION** run at least ONE graph command on key files when graph.db exists. Pattern: grep → graph trace → grep verify. **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 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** 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. **IMPORTANT MUST ATTENTION** debugger trace gate: for non-trivial bug/fix/investigation/review work, start at the observed final output and trace backward through reader -> storage/projection -> writer -> consumer/job -> producer/trigger. Enumerate all feeder paths and hypotheses before fixing. **BLOCKED until** trace, hypothesis matrix, owning fix layer, and forward convergence proof exist. - **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. - **MANDATORY** Resolve the active Goal Contract BEFORE work (active plan `goal.md` → `plans/goals/{YYMMDD-HHmm}-{slug}/goal.md` → create from current request) and read saved success criteria before editing. - **MANDATORY** Append iteration evidence after execution; emit a Goal Satisfaction matrix (PASS/FAIL/BLOCKED) before reporting PASS; loop on validated FAIL; escalate repeated no-progress or blockers. NEVER store secrets in goal files. > **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 `/.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 `/.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:** Ship a correct, fully-verified feature that satisfies the saved Goal Contract — research-backed, planned, reviewed, tested, documented — with no skipped quality gate on any non-trivial change. **IMPORTANT MUST ATTENTION — Protocols in force (concise digest of the SYNC/shared blocks this skill carries; each line is a signpost to its canonical body above):** - **End-To-Start Debugger Trace:** Trace observed output backward through every feeder path before fixing. - **Source/Test Drift Check:** When source behavior changes, reconcile affected tests from evidence. - **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity. - **UI System Context:** Read frontend, SCSS, and design-system docs before any UI change. - **Graph-Assisted Investigation:** Run a graph command on key files when graph.db exists. - **Nested Task Creation:** Expand child phase tasks and link the parent when nested. - **Project Reference Docs Guide:** Read required project-reference docs (always `lessons.md`) before target work. - **Task Tracking External Report:** Bootstrap task tracking; persist plan/review findings incrementally to disk. - **Critical Thinking Mindset:** Critical + sequential thinking; every claim needs traced proof, confidence >80%. - **Understand Code First:** Search 3+ patterns and read code before any modification. - **Plan Quality:** Add `## Test Specifications` with TC IDs to every plan phase. - **MANDATORY IMPORTANT MUST ATTENTION** default mode HARD — opt out to fast mode ONLY when ALL trivial-task conditions met - **MANDATORY IMPORTANT MUST ATTENTION** break work into small todo tasks via task tracking BEFORE starting - **MANDATORY IMPORTANT MUST ATTENTION** search codebase for 3+ similar patterns before creating new code - **MANDATORY IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim (confidence >80% to act) - **MANDATORY IMPORTANT MUST ATTENTION** add final review todo task to verify work quality - **MANDATORY IMPORTANT MUST ATTENTION** validate decisions with user by asking the user directly — never auto-decide - **MANDATORY IMPORTANT MUST ATTENTION** NEVER skip `code-reviewer` review or test execution on non-trivial change **[TASK-PLANNING]** Before acting, analyze task scope and systematically break into small todo tasks and sub-tasks via task tracking. --- > **Closing reminder — Easy to Change is the success metric.** Every finding, > test, refactor, and abstraction must answer one question: _does this make > the next change cheaper or more expensive?_ If it doesn't reduce future > change cost, reject it. Coupling, hidden state, duplicated knowledge, and > unclear intent are the real enemies — call them out by name. ## Hookless Prompt Protocol Mirror (Auto-Synced) Source: `.claude/.ck.json` + `.claude/skills/shared/sync-inline-versions.md` (`:full` blocks) + `.claude/scripts/lib/hookless-prompt-protocol.cjs` ## [WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] Workflow Execution Protocol — MANDATORY IMPORTANT MUST CRITICAL. Do not skip for any reason. **Generic portability boundary:** Reusable skills and protocol text stay project-neutral; project-specific conventions are discovered from docs/project-config.json and docs/project-reference/. Apply shared AI-SDD from `shared/sdd-artifact-contract.md`. Read `docs/project-config.json` and `docs/project-reference/docs-index-reference.md`, then open the project reference docs named there. For spec, test-case, behavior-change, public-contract, or `docs/specs/` work, route through the local spec docs named by the docs index: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md`, and `workflow-spec-test-code-cycle-reference.md` when specs/tests/code must stay synchronized. If either file or a required reference doc is missing or stale, auto-run `$project-init` (or the narrow lower-level route such as `$project-config`, `$docs-init`, `$scan-all`, or `$scan --target=`) before ordinary project-specific work. …(truncated)