القائمة
[Documentation] Use when updating impacted documentation after code, spec, or test changes.
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/duc01226/EasyPlatform --skill docs-updateيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
عرض SKILL.md
[Architecture] Use when designing solution architecture across backend, frontend, deployment, monitoring, testing, and code quality.
[Utilities] Use when you need to answer technical and architectural questions.
[Content] Use when you need to brainstorm as a PO/BA — structured ideation for problem-solving, new product creation, or feature enhancement.
استنادا إلى تصنيف SOC المهني
| name | docs-update |
| version | 3.3.0 |
| description | [Documentation] Use when updating impacted documentation after code, spec, or test changes. |
[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_progresswhen step starts, setcompletedwhen 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.
Goal: Detect impacted docs from code changes and orchestrate updates across all doc types so every code/spec/test change leaves documentation in sync — impacted Feature Specs, §8 TCs, test-code links, and derived indexes all reflect the shipped behavior, with zero drift left silent.
Summary:
/spec, /spec [mode=tests], /spec [mode=sync], /spec-index); NEVER write §8 or docs/specs/ content directly.TaskCreate before touching any file; run the fixed phase order 0 → 1 → 2 → 2.5 → 3 → 4 → 5 → final review and mark every skipped phase completed with a reason — fast-exit is a decision, never a silent omission.FR-/BR-/OP-/TC- logical IDs before prose); ALWAYS write the Phase 5 summary report as the audit trail.Orchestration Model:
git diff → Triage → Phase 1: Project Docs (inline)
→ Phase 2: /spec (business feature docs)
→ Phase 2.5: /spec-index (derived index/ERD refresh) [optional]
→ Phase 3: /spec [mode=tests] (§8 test specifications)
→ Phase 4: /spec [mode=sync] (§8 ↔ test code sync)
→ Phase 5: Summary Report
Key Rules:
docs/specs/ content$ARGUMENTSin_progress -> execute -> completed (or completed with skip reason).claude skills/hooks/workflows/sync tooling changes, flag generated mirror sync status (npm run codex:sync completed or explicit N/A). docs-update routes and reports this check; it does not edit generated mirrors directly.**Evidence**, IntegrationTest, [Source:], frontmatter, Mermaid). Authority: docs/project-reference/spec-principles.md §3..claude/skills/shared/sdd-artifact-contract.md → "AI-SDD Mandates (M1-M6)" for BLOCKING criteria. When syncing docs after code changes, update the logical-ID mappings (FR-/BR-/OP-/TC-) FIRST, then the prose. The [Source: namespace/service/id] abstract-anchor evidence is re-resolved ONLY if the logical artifact was renamed/split — a file move or stack change does NOT change the anchor (physical coords live only in the provenance sidecar) — and the logical-ID spine stays stable across the change — never drop or renumber a logical ID just because the code moved. Keep all synced prose M1/M2-clean.Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80%.
[BLOCKING] Create ALL 8 tasks via
TaskCreateBEFORE touching any file. NEVER consolidate, rename, omit. Conditional tasks skipped: markcompletedimmediately with reason — NEVER silently omit.
| # | Task Subject | Conditional? |
|---|---|---|
| 1 | [docs-update] Phase 0 — Triage: collect git diff, categorize files, detect modules, check existing docs | No — always first |
| 2 | [docs-update] Phase 1 — Update project docs (project-structure-reference.md, README.md) | Yes — only if configured framework/shared source paths or architectural changes are in diff |
| 3 | [docs-update] Phase 2 — Invoke /spec: update business feature docs | Yes — service/frontend files changed AND module has existing feature docs |
| 4 | [docs-update] Phase 2.5 — Invoke /spec-index [mode=index]: refresh derived bucket INDEX/ERD | Yes — a Feature Spec changed AND the bucket maintains a derived index/ERD |
| 5 | [docs-update] Phase 3 — Invoke /spec [mode=tests]: update/add §8 test specifications | Yes — new functionality added OR existing behavior changed |
| 6 | [docs-update] Phase 4 — Invoke /spec [mode=sync]: sync §8 ↔ test code | Yes — Phase 3 changed §8 TCs |
| 7 | [docs-update] Phase 5 — Write summary report to plans/reports/docs-update-{YYMMDD}-{HHMM}.md | No — always |
| 8 | [docs-update] Final review — verify all impacted docs updated, no phases skipped without justification, AND run the Step 2.4 code↔spec sync-verify (AC/BR/TC drift) for every touched module | No — always |
Execution rules:
in_progress when starting, completed when done — one active at a timecompleted with reason "Skipped — no business code changed"in_progresswhat ran, what changed, why skipped)TaskCreate/task updates unavailable, maintain equivalent 8-task plan tracker with same status transitions| Order | Task ID | Step / Phase | Skill Call | Tracking Rule |
|---|---|---|---|---|
| 1 | 1 | Phase 0: Triage | Inline triage logic in this skill | Set Task 1 in_progress before diff scan; set completed after module + impact map recorded |
| 2 | 2 | Phase 1: Project Docs | docs-manager sub-agent (if impacted) | Set Task 2 in_progress before spawn/update; completed with updated docs or skip reason |
| 3 | 3 | Phase 2: Business Feature Docs | /spec | Set Task 3 in_progress before invocation; completed after output review |
| 4 | 4 | Phase 2.5: Derived Index Refresh | /spec-index [mode=index] | Set Task 4 in_progress before invocation; completed after INDEX rows match Feature Specs |
| 5 | 5 | Phase 3: §8 Test Specs | /spec [mode=tests] | Set Task 5 in_progress before invocation; completed after TC review |
| 6 | 6 | Phase 4: §8 ↔ Test Code Sync | /spec [mode=sync] | Set Task 6 in_progress before invocation; completed after sync validation |
| 7 | 7 | Phase 5: Summary Report | Inline report write | Set Task 7 in_progress before report write; completed after file path confirmed |
| 8 | 8 | Final Review | Inline verification gate | Set Task 8 in_progress before final audit; completed after all phases justified |
Enforcement: If a required step cannot run, STOP and ask user before adapting order. Never continue with untracked steps.
git diff --name-only HEAD (staged + unstaged changes)git diff --name-only HEAD~1 (last commit)git diff --name-only origin/develop...HEAD (branch changes)| Changed File Pattern | Impact Category | Phases to Run |
|---|---|---|
{backend-source-paths}/** from docs/project-config.json | spec + spec [mode=tests] + project-docs | 1 + 2 + 3 + 4 |
{frontend-apps-dir}/**, {frontend-libs-dir}/{domain-lib}/** | spec + spec [mode=tests] + project-docs | 1 + 2 + 3 + 4 |
{legacy-frontend-dir}/**Client/** | spec + spec [mode=tests] + project-docs | 1 + 2 + 3 + 4 |
{configured-framework-source-paths}/** | project-docs only | 1 only |
docs/** | project-docs only | 1 only |
.claude/**, config files only | none | Fast exit |
{frontend-libs-dir}/{framework-core-lib}/**, {frontend-libs-dir}/{common-lib}/** | project-docs only | 1 only |
ALL changed files in none category (only .claude/, .github/, root config):
"No documentation impacted by current changes (config/tooling only)."completed with reason "Skipped — no business code changed"Extract unique module names from changed paths. MUST ATTENTION dedup: unique() before passing to any sub-skill — backend + frontend same module = ONE entry. Prevents duplicate /spec invocations.
| Changed File Path Pattern | Detected Module |
|---|---|
{backend-module-path}/{Module}/** | {Module} |
{frontend-apps-dir}/{app-name}/** | {Module} (map app to module) |
{frontend-libs-dir}/{domain-lib}/{configured-feature-path}/** | {Module} (map feature to module) |
{legacy-frontend-dir}/{Module}Client/** | {Module} |
Build project-specific mapping from docs/project-config.json and project reference docs, not from hard-coded skill paths:
node -e "const cfg=require('./docs/project-config.json'); console.log(JSON.stringify({sourcePaths: cfg.codebaseHealth?.sourcePaths, contextGroups: cfg.contextGroups?.map(g => ({name:g.name,pathRegexes:g.pathRegexes})), specRoot: 'docs/specs/'}, null, 2))"
node -e "process.stdout.write('docs/specs/')"
For each detected module:
docs/specs/README.*.md Feature Specs, or use the project reference doc's feature-doc layoutdocs/specs/ exists using project reference docshasFeatureSpec (§1–§7 present), hasTestSpecs (§8 present), hasDerivedIndex (bucket INDEX.md present)When to run: Diff includes configured framework/shared source paths, docs/**, or architectural changes.
When to skip: Only service-layer or frontend feature files changed. Skip → proceed to Phase 2.
Standalone (not workflow step): spawn 2-4 scout-external (preferred) or scout (fallback) via Task. Merge results into context.
Workflow step: skip — use Phase 0 git diff context.
Pass context to docs-manager sub-agent (subagent_type="docs-manager") for project doc updates:
docs/project-reference/project-structure-reference.md — update if service architecture or cross-service patterns changedREADME.md — update if project scope or setup changed (keep under 300 lines)NEVER regenerate all docs — only update docs directly impacted by changes.
/specWhen to run: Triage detected modules with hasFeatureDocs = true AND service/frontend files changed.
When to skip: No service/frontend feature files changed. Report: "No business feature docs impacted."
| Scenario | Action |
|---|---|
| Module has existing feature docs | Invoke /spec — auto-detect triggers update flow |
| Module has NO feature docs AND change adds/changes a feature (new endpoint, command/query, entity, business rule, user-facing behavior) | BLOCK — Report: "Module {Module} has NO Feature Spec but this change introduces feature behavior. Create the tech-free 8-section Feature Spec FIRST via /spec, then re-run docs-update." Do NOT skip. This is the doc-first gate. |
| Module has NO feature docs AND change is tooling/style/config-only (no behavioral impact) | Skip with reason "No feature behavior changed — no Feature Spec required." (matches Phase 0 fast-exit at :113-120). |
| User explicitly asked for full doc creation | Invoke /spec with explicit module name |
/spec/spec Update feature docs for modules: {detected modules}.
Changed files: {list from triage}.
Impacted sections based on change types: {section impact from triage}.
Mode: update (existing docs only, do not create from scratch).
What /spec handles (DO NOT duplicate here):
INDEX.md catalog row update[Source:] only)/spec Output/spec for missed sectionsPurpose: docs-update already runs LAST in feature/bugfix/big-feature, so this is the workflow's final gate. It is the order-time partner of the Phase 4 commit hook (this step guides; the hook enforces). Verify the SHIPPED code actually matches the mapped tech-free 8-section Feature Spec before the workflow completes.
For each module touched in this run, diff the changed code against its Feature Spec and check three sets:
| Spec set (Feature Spec section) | Sync check against changed code | On drift |
|---|---|---|
| §3 Acceptance Criteria (AC-{FC}-NN) | Every changed user-facing behavior maps to an AC; new behavior with no AC = missing AC. | Report drift; re-invoke /spec to add the AC. |
| §4 Business Rules (BR-{FC}-NNN, [HARD]/[SOFT]) | Each changed validation/invariant matches a BR; a [HARD] rule whose code path was removed/weakened = regression. | BLOCK — surface as a code-vs-spec contradiction for the author to resolve. |
§8 Test Specifications (TC-{FC}-NNN + IntegrationTest:) | Each new/changed behavior has a TC; each Tested TC's IntegrationTest: {File}::{Method} still resolves. | Report; route to /spec [mode=sync]. |
Output: a short sync-verify table (module · AC drift · BR drift/contradiction · TC drift) appended to the docs-update report. Clean = no drift across all three. A [HARD]-BR contradiction blocks workflow completion until resolved or explicitly accepted by the owner.
Scope: business code↔spec drift only. Technical contracts (API routes/DTOs, bus/job mechanics) are code-canonical and intentionally NOT re-verified against prose. No new sequence step and no
verify-syncmode is added — this responsibility lives inside docs-update's existing final pass.
[SINGLE-HOME] There is no separate "engineering spec bundle". The canonical artifact is the 8-section Feature Spec updated in Phase 2.
spec-indexis repurposed to regenerate only the DERIVED bucketINDEX.md/ cross-capability ERD from those Feature Specs — it never re-extracts an A-E tree. Run this phase only if the bucket maintains a derived index/ERD that the Phase 2 change made stale.
When to run: Phase 2 changed one or more Feature Specs AND the bucket maintains a derived INDEX.md / ERD aid that now lags.
When to skip:
docs/, .claude/, or config files changeddocs/specs/{Bucket}/ was touchedproject-config.json contains "spec_discovery_update": falsespec already refreshed INDEX.md in Phase 2 (no separate refresh needed)docs/project-reference/spec-system-reference.md → App Bucket Mapping.docs/specs/{Bucket}/ holds the updated Feature Spec(s)./spec-index mode=index bucket={Bucket} artifacts=INDEX[,ERD]
Source: the canonical Feature Specs in docs/specs/{Bucket}/.
Output: regenerated DERIVED docs/specs/{Bucket}/INDEX.md (+ {Bucket}.erd.md if maintained), each carrying the DERIVED banner.
INDEX.md rows match the current set of Feature Specs (no dangling links, no missing capabilities)."Derived index refreshed: {Bucket} — {N} capabilities catalogued".Separation of concerns:
docs-updateorchestrates — passes the bucket scope to spec-index. NEVER hand-edits the derived index, and NEVER recreatesM##/A-E artifacts (retired).
/spec [mode=tests]When to run: New functionality added (commands, queries, endpoints, components) OR existing behavior changed.
When to skip: Changes purely cosmetic (styling, comments, docs-only) with no behavioral impact.
| Context | TC Mode |
|---|---|
| New feature code, no existing TCs | implement-first |
| PBI/story exists, code not yet written | TDD-first |
| Existing TCs + code changes / bugfix | update |
| User says "sync test specs" | sync |
| Tests exist with annotations, no docs | from-integration-tests |
PBI/idea artifact route: when changed artifacts match configured PBI/idea artifact roots from docs/project-config.json or project reference docs, docs-update performs detection/delegation only. It may identify affected module, feature doc, and TC scope, then route to /spec, /spec [mode=tests], or /spec [mode=sync]. It must not generate TC content directly from PBI/idea artifacts or edit Section 8 itself. If artifact roots are not configured, ask the user to initialize project config/reference docs before assuming a path.
/spec [mode=tests]/spec [mode=tests] Mode: {detected mode}.
Modules: {detected modules}.
Changed files: {list from triage}.
New functionality detected: {new commands/queries/endpoints from diff analysis}.
What /spec [mode=tests] handles (DO NOT duplicate here):
/spec [mode=tests] Output/spec [mode=sync]When to run: Phase 3 produced new/updated TCs in §8 of a Feature Spec.
When to skip: No §8 test-spec changes.
/spec [mode=sync]/spec [mode=sync] Sync test specs for capabilities: {detected features}.
Direction: forward (Feature Spec §8 Test Specifications → integration test code).
Updated TCs from Phase 3: {list of new/changed TC IDs}.
What /spec [mode=sync] handles (DO NOT duplicate here):
TestSpec and the per-TC IntegrationTest: field)The retired QA dashboards (
docs/specs/README.md,docs/specs/PRIORITY-INDEX.md) and theA-E/M##engineering tree no longer exist — §8 is the canonical TC registry. The only derived TC roll-up is the bucketINDEX.mdcount, refreshed in Phase 2.5.
TestSpec annotation but absent from §8).Which skill owns which doc sections — docs-update delegates only, NEVER writes directly:
| Section | Owner Skill | docs-update Role |
|---|---|---|
| §1–§7 (Feature Spec, tech-free) | /spec | Pass triage context; review output |
| §8 (Test Specifications) | /spec [mode=tests] | Pass TC mode + changed files; NEVER write TCs here |
| §8 ↔ test code sync | /spec [mode=sync] | Pass capability list + direction; NEVER edit directly |
Derived bucket INDEX.md / ERD | /spec-index (optional) | Pass bucket scope; NEVER hand-edit the derived index |
ALWAYS write full report to plans/reports/docs-update-{YYMMDD}-{HHMM}.md:
### Documentation Update Summary
**Triage:** {N} files changed → {categories detected}
**Modules detected:** {module list}
**Generated mirror sync:** {Completed / N/A / Required before close}
**Phase 1 — Project Docs:**
- {Updated/Skipped}: {reason}
**Phase 2 — Feature Specs (/spec):**
- {Capability X}: {Updated §1–§7 / No existing Feature Spec / Not impacted}
- {Capability Y}: {Updated §4 Business Rules, §5 Domain Model / Skipped: no Feature Spec}
**Phase 2.5 — Derived Index Refresh (/spec-index, optional):**
- {Refreshed {Bucket} INDEX.md ({N} capabilities) / Skipped: no derived index maintained / Skipped: spec_discovery_update=false}
**Phase 3 — Test Specifications §8 (/spec [mode=tests]):**
- Mode: {mode used}
- New TCs: {list of TC IDs added}
- Updated TCs: {list of TC IDs modified}
- Skipped: {reason if skipped}
**Phase 4 — Test Spec ↔ Test Code Sync (/spec [mode=sync]):**
- {Synced N TCs to test code / Skipped: no §8 changes}
- Discrepancies: {§8-vs-test-code comparison issues}
**Recommendations:**
- {New docs that should be created}
- {Stale docs flagged but not auto-fixed}
- {TCs flagged as Untested}
| Scenario | Use docs-update? | Use skill directly? |
|---|---|---|
| Post-implementation doc sync (any code change) | Yes — full orchestration | — |
| Create new feature docs from scratch | No | /spec |
| Generate TCs for specific PBI (TDD-first) | No | /spec [mode=tests] |
| Route PBI/idea artifact changes | Yes — detection/delegation | /spec + /spec [mode=tests] owner skills |
| Sync dashboard only (no code changes) | No | /spec [mode=sync] |
Workflow step after /plan-execute or /fix | Yes — full orchestration | — |
| User asks "update docs after my changes" | Yes — full orchestration | — |
Pass caller context via $ARGUMENTS to skip redundant triage or narrow scope:
| Key | Example | Effect |
|---|---|---|
modules | modules=ModuleA,ModuleB | Skip auto-detect; use provided list |
changed_files | changed_files=<configured-source-path>/ModuleA/... | Skip git diff; use provided file list |
phases | phases=2,3 | Run only specified phases |
mode | mode=update | Override spec mode detection |
tc_mode | tc_mode=implement-first | Override spec [mode=tests] mode detection |
skip_phases | skip_phases=1,2.5 | Skip specific phases |
<additional_requests> $ARGUMENTS </additional_requests>
| Situation | What to do instead |
|---|---|
| Feature Spec missing but capability exists | Run /spec [mode=init] to author the 8-section Feature Spec, then docs-update |
Derived bucket INDEX.md/ERD missing | Run /spec-index mode=index bucket={Bucket} to (re)generate it |
| Integration tests don't match TCs | Run /integration-test-review to diagnose, then /integration-test to fix |
| Bug caused by wrong spec | Run /spec [mode=update] (fix the canonical spec) BEFORE docs-update; optionally /spec-index mode=index to re-derive the bucket index |
[BLOCKING] Create ALL 8 tasks via
TaskCreateBEFORE any action — see Mandatory Task Creation table. NEVER skip, batch-complete, or mark done without invoking sub-skill. [BLOCKING] Follow fixed step-skill order:Phase 0 -> Phase 1 -> Phase 2 -> Phase 2.5 -> Phase 3 -> Phase 4 -> Phase 5 -> Final review. NEVER reorder, merge, or skip without explicit user approval. [BLOCKING] Per-step task lock: BEFORE each step, mark taskin_progress; AFTER each step, mark taskcompletedwith evidence or explicit skip reason. [BLOCKING] If Task tool unavailable, create equivalent 8-step plan tracker and keep statuses synced for every step.
Critical Purpose: Single orchestrator for ALL documentation sync after code changes. Triages impact, delegates to specialized skills.
Evidence Gate: [BLOCKING] — every claim requires
file:lineproof or traced evidence, confidence >80% to act.
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.
Sub-Agent Return Contract — When this skill spawns a sub-agent, the sub-agent MUST return ONLY this structure. Main agent reads only this summary — NEVER requests full sub-agent output inline.
## Sub-Agent Result: [skill-name] Status: ✅ PASS | ⚠️ PARTIAL | ❌ FAIL Confidence: [0-100]% ### Findings (Critical/High only — max 10 bullets) - [severity] [file:line] [finding] ### Actions Taken - [file changed] [what changed] ### Blockers (if any) - [blocker description] Full report: plans/reports/[skill-name]-[date]-[slug].mdMain agent reads
Full reportfile ONLY when: (a) resolving a specific blocker, or (b) building a fix plan. Sub-agent writes full report incrementally (per SYNC:incremental-persistence) — not held in memory.Context budget — the return payload is a SUMMARY, not a transcript: ≤10 finding bullets, no raw file contents / full diffs / verbatim logs inline, no re-pasted source. Everything beyond the summary lives in the
Full reporton disk. A sub-agent that would exceed the summary shape MUST write the detail to its report and return only the pointer — the orchestrator's context is the scarce resource the whole map-reduce protects.
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,IntegrationEventEvent consumers Consumer,EventHandler,Subscribe,@EventListener,inboxSagas/orchestration Saga,ProcessManager,Choreography,Workflow,OrchestratorSync 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. Before changing a constant, limit, flag, wording, or pattern, read nearby context and history. Surface ambiguity before acting — don't pick silently. Multiple valid interpretations require an explicit question or stated assumption with risk. Keep shared guidance role-relevant. Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.
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
TaskListfirst. If a matching active parent workflow row exists, setnested=trueand recordparentTaskId; 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_progressbefore work andcompletedimmediately after evidence is written.- Complete the parent only after all child tasks are completed or explicitly cancelled with reason.
Blocked until:
TaskListdone, child phases created, parent linked when nested, first child markedin_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.
- Identify scope: file types, domain area, and operation.
- Required docs by trigger: always
docs/project-reference/lessons.md; doc lookupdocs-index-reference.md; reviewcode-review-rules.md; backend/CQRS/APIbackend-patterns-reference.md; domain/entitydomain-entities-reference.md; frontend/UIfrontend-patterns-reference.md; styles/designscss-styling-guide.md+design-system/design-system-canonical.md; integration testsintegration-test-reference.md; E2Ee2e-test-reference.md; feature docs/specsfeature-spec-reference.md+spec-system-reference.md+spec-principles.md; behavior/public-contract/spec-test-code syncworkflow-spec-test-code-cycle-reference.md; derived spec index/ERD/reimplementation guidesspec-system-reference.md+ source Feature Specs underdocs/specs/; architecture/new areaproject-structure-reference.md.- Read every required doc. 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-initor the narrow lower-level route (/project-config,/docs-init,/scan-all,/scan --target=<key>,/claude-md-init) before ordinary project-specific work. If Codex mirrors orAGENTS.mdare missing/stale, ask the user to run/sync-codex; do not auto-run it.- Before target work, state:
Reference docs read: ... | Not applicable: ....Ready when: scope evaluated, required docs checked/read or setup route completed,
lessons.mdconfirmed, citation emitted.
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_progressbefore work andcompletedimmediately after evidence; never batch transitions.- For plan/review work, create
plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.mdbefore 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.
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.
plans/reports/ incrementally and synthesize from disk.Reference docs read: ....lessons.md; project conventions override generic defaults./project-init or the narrow lower-level route before ordinary project-specific work.[N.M] $skill-name — phase prefixes and one-in_progress discipline.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
IMPORTANT MUST ATTENTION Goal: Every code/spec/test change leaves documentation in sync — impacted Feature Specs, §8 TCs, test-code links, and derived indexes all reflect the shipped behavior, with zero drift left silent.
Protocols in force (concise digest of the SYNC/shared blocks this skill carries) — MUST ATTENTION honor every block below:
file:line proof, confidence >80%.lessons.md) before target work.plans/reports/ incrementally.IMPORTANT MUST ATTENTION create ALL 8 tasks via TaskCreate BEFORE any action, then run the FIXED order 0 -> 1 -> 2 -> 2.5 -> 3 -> 4 -> 5 -> final review — NEVER reorder, merge, or skip without explicit user approval — why: phase order is the gate that catches drift; a skipped phase ships silent staleness
IMPORTANT MUST ATTENTION docs-update is a ROUTER ONLY — delegate to /spec, /spec [mode=tests], /spec [mode=sync], /spec-index; NEVER write §8 content, edit Feature Spec / derived-index files, or duplicate sub-skill logic — why: dual authorship causes the two sources to diverge
IMPORTANT MUST ATTENTION every skip is a DECISION with evidence — mark the task completed with a file:line-backed reason; NEVER silently omit a phase — why: an unjustified skip is indistinguishable from a missed update
MUST ATTENTION Nested Task Expansion Contract — when invoked inside a workflow, STILL expand internal phases via TaskCreate with [N.M] $skill-name — phase prefix and TaskUpdate(parentTaskId, addBlockedBy: [childIds]) linkage — why: the workflow row is a container, not a substitute for phase tracking
MUST ATTENTION for EVERY step: set task in_progress BEFORE execution, set completed AFTER execution with evidence or skip reason — never batch transitions, keep exactly one active
MUST ATTENTION if task tooling unavailable, use an equivalent 8-step plan tracker and keep statuses synced per step
MUST ATTENTION evidence gate — every claim, detected module, and impact mapping needs file:line / git-diff proof, confidence >80% to act, <60% DO NOT act; "Module unchanged" without proof is NOT a valid skip — why: speculation routes the wrong docs and misses real drift
MUST ATTENTION search-existing-patterns BEFORE asserting a doc shape — read the bucket's existing Feature Spec / INDEX layout and project-reference docs; build the module map from docs/project-config.json, NEVER from hard-coded skill paths — why: local doc conventions override generic assumptions
MUST ATTENTION evaluate fit before reusing a nearby pattern — a module with backend + frontend changes is ONE deduped entry, not two; verify the change actually alters behavior before routing to /spec — why: duplicate or behavior-free invocations waste passes and corrupt the audit
MUST ATTENTION validate ambiguous routing decisions with the user via AskUserQuestion — surface the options, NEVER silently auto-decide which phases run
MUST ATTENTION tech-agnostic output — when updating spec/specs/README/INDEX, introduce NO framework/product/language/pattern names in prose or headings; update logical IDs (FR-/BR-/OP-/TC-) FIRST, then prose; preserve the evidence-field exception — why: prose is the portable contract, evidence carriers hold the physical coords (spec-principles §3)
MUST ATTENTION Step 2.4 final code↔spec sync-verify per touched module — a removed/weakened [HARD] BR is a code-vs-spec contradiction that BLOCKS completion until resolved or owner-accepted; AC drift re-invokes /spec, TC drift routes to /spec [mode=sync]
MUST ATTENTION Phase 2.5 /spec-index [mode=index] OPTIONALLY refreshes the derived bucket INDEX/ERD from Feature Specs (never re-extracts an A-E tree); Phase 3 /spec [mode=tests] syncs §8 TCs; Phase 4 /spec [mode=sync] syncs §8 TCs ↔ integration test code (no QA dashboard exists)
MUST ATTENTION for .claude skills/hooks/workflows/sync-tooling changes, flag generated-mirror sync status (npm run codex:sync completed or explicit N/A) — docs-update routes/reports this check, NEVER edits generated mirrors directly
MUST ATTENTION ALWAYS write the Phase 5 summary report to plans/reports/docs-update-{YYMMDD}-{HHMM}.md and the final review task (#8) — the report is the audit trail, the review verifies all impacted docs updated with no unjustified skips
Anti-Rationalization:
| Evasion | Rebuttal |
|---|---|
| "Only docs/config changed — skip all phases" | Run Phase 0 triage anyway — fast-exit is a DECISION, not an assumption |
| "No feature docs exist — skip Phase 2" | Mark task completed with reason. NEVER silently omit |
| "Module unchanged — skip sub-skill" | Show file:line evidence. No proof = no skip |
| "Already know what changed" | Still run git diff — partial knowledge causes missed updates |
| "Phase 5 report not needed" | ALWAYS write summary report — it's the audit trail |
| "I will update tasks later" | Invalid. Task status must change before/after each step in real time. |
| "I'll run skills first then create tasks" | Invalid. Create/track tasks first, then execute step-skill calls. |
| "I'll write the §8 TC myself, faster" | Invalid. Router only — delegate to /spec [mode=tests]; dual authors diverge. |
| "[HARD] BR weakened but tests pass" | BLOCK — code-vs-spec contradiction; resolve or owner-accept, never wave through. |
IMPORTANT MUST ATTENTION create ALL 8 tasks via TaskCreate (or equivalent tracker) BEFORE any action and track each step live — in_progress before, completed after with evidence.
IMPORTANT MUST ATTENTION router ONLY — delegate every §8 / Feature Spec / derived-index write; NEVER author them here — why: dual authorship diverges the spec from its index.
IMPORTANT MUST ATTENTION every skip needs file:line evidence and a completed task with reason; run the fixed phase order — NEVER silently omit a phase.