docs-update

Imported from duc01226/easy-claude (.agents/skills/docs-update/SKILL.md). Install upstream with npx skills add duc01226/easy-claude --skill docs-update. Copyright stays with the author.

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=<key>, $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, 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: Keep docs synchronized after every code/spec/test change: triage impact, route each doc type to its owner, and align project-reference/config docs, Feature Specs, §8 TCs, test-code links, and derived indexes with shipped behavior — zero silent drift.

Summary:

• This skill is a ROUTER, not an author — start with Phase 0 triage (git diff → categorize → dedup modules → check existing docs) and delegate each doc type to its owner ($spec, $spec [mode=tests], $spec [mode=sync], $spec-index, $tech-spec for derived technical views); NEVER write §8, docs/specs/, or derived technical spec content directly. — why: dual authorship diverges spec from index/view.
• Main steps (each impact-gated; skipped phase → mark completed with reason): Phase 0 triage (git diff → categorize → dedup modules → record existing-doc state) → Phase 1 project context sync (impact-map → PARALLEL verify of the impacted docs/project-reference/** docs + docs/project-config.json sections + README.md) → Phase 2 $spec (§1–§7 Feature Spec; doc-first BLOCK when feature behavior changed but no Spec exists) → Phase 2.5 $spec-index (derived bucket INDEX/ERD refresh, optional) → Phase 2.6 $tech-spec (derived technical view refresh/audit, optional when technical tree is affected) → Phase 3 $spec [mode=tests] (§8 TCs) → Phase 4 $spec [mode=sync] (§8 ↔ test code) → Phase 5 summary report → final review (#8 runs the Step 2.4 code↔spec sync-verify).
• Create ALL 8 tasks via task tracking before touching any file; run the fixed phase order 0 → 1 → 2 → 2.5/2.6 → 3 → 4 → 5 → final review — fast-exit is a decision, never a silent omission.
• The final pass (Step 2.4) is the workflow's last gate: per touched module verify shipped code against §3 ACs, §4 BRs, §8 TCs — a removed/weakened [HARD] BR is a code-vs-spec contradiction that BLOCKS completion.
• Output is tech-agnostic prose (no framework/product names outside evidence fields) and traceability-first (update FR-/BR-/OP-/TC- logical IDs before prose); ALWAYS write the Phase 5 summary report as the audit trail.

Workflow:

• MUST ATTENTION run Phase 0 triage → Phase 1 impact-scoped context sync → Phase 2 $spec → Phase 2.5 $spec-index (if needed) → Phase 2.6 $tech-spec (if needed) → Phase 3 $spec [mode=tests] → Phase 4 $spec [mode=sync] → Phase 5 report → final Step 2.4 code↔spec sync-verify; track each task before/after and record every skip.

Orchestration Model:

git diff → Triage → Phase 1: Project Context Sync (PARALLEL, impact-scoped)
                  │            ├─ impacted docs/project-reference/** — verify → patch → (escalate to $scan --target=X)
                  │            ├─ impacted docs/project-config.json sections — verify → merge → validate
                  │            └─ README.md / project docs (docs-manager)
                  → Phase 2: $spec (business feature docs)
                  → Phase 2.5: $spec-index (derived index/ERD refresh) [optional]
                  → Phase 2.6: $tech-spec (derived technical view refresh/audit) [optional]
                  → Phase 3: $spec [mode=tests] (§8 test specifications)
                  → Phase 4: $spec [mode=sync] (§8 ↔ test code sync)
                  → Phase 5: Summary Report

Key Rules:

• Router only — NEVER duplicate sub-skill logic or write Section 8 / docs/specs/ content
• [BLOCKING] Freshness is impact-scoped, never assumed. Phase 1 verifies only the docs/project-reference/** docs and docs/project-config.json sections the diff can actually rot (routed by node .claude/scripts/doc-impact-map.cjs), and reports a per-doc verdict FRESH | PATCHED | RESCAN REQUIRED | UNVERIFIED. A doc nobody checked is UNVERIFIED — NEVER FRESH. — why: these docs are injected into every downstream AI context, so a silent stale line teaches every later agent a codebase that no longer exists.
• [BLOCKING] An impact-scoped verify NEVER writes <!-- Last scanned: -->. Only a full $scan --target=X may move that stamp; the narrow pass writes <!-- Last verified: ... --> instead — and only in a doc that already carries a Last scanned stamp (Step 1.6). — why: Last scanned drives the 60-day full-rescan gate (.claude/hooks/lib/session-init-helpers.cjs:769); resetting it from a partial check would buy speed by disabling the very net that catches whole-doc rot.
• [BLOCKING] A PATCHED docs/project-reference/** doc MUST run $prompt-enhance <doc> before its verdict is final (Step 1.3) — keeps the doc as concise as possible while staying valuable enough for AI; skip only for a stamp/count-only edit.
• Phase 1/docs-manager MUST NOT own any docs/specs/**, test-spec, spec-index/ERD, or derived technical-view path.
• Every excluded artifact is explicitly reserved to its child skill ($spec, $spec-index, or $tech-spec) so one canonical writer owns it.
• Exclude docs/specs/** and generated technical views from every docs-manager brief and write set.
• Each phase checks whether needed before invoking — skip phases with no impact
• Step-to-skill order is fixed — run phases sequentially, never out of order
• ALWAYS report what was checked, even if nothing needed updating
• Pass triage context (changed files, detected modules, impacted sections) to each sub-skill via $ARGUMENTS
• MUST ATTENTION dedup module list — backend + frontend changes for same module = ONE entry
• MUST ATTENTION track step state live: in_progress -> execute -> completed (or completed with skip reason)
• 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 and reports this check; it does not edit generated mirrors directly.
• [BLOCKING] Tech-agnostic output: when updating spec/specs/README/INDEX, do NOT introduce framework/product/language/design-pattern names into prose or headings — preserve the evidence-field exception (**Evidence**, CoveredBy, legacy IntegrationTest, [Source:], frontmatter, Mermaid). Authority: docs/project-reference/spec-principles.md §3.
• [BLOCKING] M3 Traceability Update: See .claude/skills/shared/sdd-artifact-contract.md → "AI-SDD Mandates (M1-M7)" 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%.

Mandatory Task Creation (ZERO TOLERANCE)

[BLOCKING] Create ALL 8 tasks via task tracking BEFORE touching any file. NEVER consolidate, rename, omit. Conditional tasks skipped: mark completed immediately with reason — NEVER silently omit.

Execution rules:

• Mark each task in_progress when starting, completed when done — one active at a time
• Multiple modules → add one subtask per module for Phase 2/3 invocations
• Multiple impacted reference docs → add one subtask per doc (or per source-of-truth cluster) under Task 2, so each doc's verdict is tracked individually
• NEVER batch-complete — each sub-skill invocation tracked individually
• Phase 0 TRUE fast-exit (impact map empty) → mark tasks 2-8 completed with reason "Skipped — impact map empty"
• Phase 0 PARTIAL exit (docs/config impacted but no business behavior — e.g. harness, CI, or manifest-only changes) → run Task 2, mark tasks 3-6 completed with reason "Skipped — no business behavior changed", still run tasks 7-8
• NEVER execute a phase step until matching task status is in_progress
• After each phase/skill call, write one-line evidence in task update (what ran, what changed, why skipped)
• If task tracking/task updates unavailable, maintain equivalent 8-task plan tracker with same status transitions

Step-Skill Call Order (Do Not Reorder)

Enforcement: If a required step cannot run, STOP and ask user before adapting order. Never continue with untracked steps.

Phase 0: Triage — Detect Impacted Documentation

Step 0.1: Collect Changed Files

1. Run git diff --name-only HEAD (staged + unstaged changes)
2. No uncommitted changes → git diff --name-only HEAD~1 (last commit)
3. Still empty → git diff --name-only origin/develop...HEAD (branch changes)

Step 0.2: Categorize Changes

This table classifies BUSINESS-doc impact (which of Phases 2-4 run). It is deliberately coarse. The precise docs/project-reference/** + docs/project-config.json routing is produced by the impact map in Step 1.1 — read it there, never guess it here.

Step 0.3: Fast Exit Check — decided by the impact map, never by path intuition

Run the impact map NOW (same command as Step 1.1) and read fastExit from its output:

node .claude/scripts/doc-impact-map.cjs --text

[BLOCKING] A .claude/**-only (or tooling-only) diff is NOT a full fast exit. Harness edits change the skill/hook/agent/workflow inventories that CLAUDE.md, docs-index-reference.md, and project-structure-reference.md derive by globbing .claude/: the counts and catalogs go stale with zero feature impact, and NO other gate in this skill catches them — Phases 2-4 only look at docs/specs/**. — why: the cheapest way to ship stale docs is to classify the change as "tooling" and skip the only phase that would have noticed.

Step 0.4: Auto-Detect Affected Modules

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.

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/')"

Step 0.5: Check Existing Docs for Each Module

For each detected module:

1. Check the matching bucket directory exists under docs/specs/
2. Check that the bucket contains README.*.md Feature Specs, or use the project reference doc's feature-doc layout
3. Check the matching bucket directory under docs/specs/ exists using project reference docs
4. Record: hasFeatureSpec (§1–§7 present), hasTestSpecs (§8 present), hasDerivedIndex (bucket INDEX.md present)

Step 0.6: Declare the Doc-Update Wave

Detection is SEQ and comes FIRST — every assignment below is derived from the impacted-doc set, so nothing dispatches until Steps 0.1–0.5 have produced it. Once that set exists, updating N unrelated docs is embarrassingly parallel: one docs-manager sub-agent per doc or per doc cluster, all spawned in ONE message.

1. Declare before dispatch — Parallel plan: wave 1 = [docs-manager: {doc A}, docs-manager: {cluster B}, …] · SEQ = [Phase 0 triage, the Phase 2 → 2.5/2.6 → 3 → 4 spec chain, Phase 5 report] (reason).
2. STRICT one-writer-per-file. Every impacted doc path appears in EXACTLY ONE agent's brief, stated as that agent's owned file set. A doc owned by nobody is a silent miss; a doc owned by two agents is a lost-update race where the later write wins and the earlier finding vanishes.
3. [HAZARD] Two docs that embed the same canonical or derived data MUST go to the SAME agent — never split across the wave. Counts, catalogs, module maps, INDEX rows, ERD entities, and any table copied out of a source of truth have to be regenerated by ONE writer from ONE reading of that source. Split across two agents they diverge inside a single commit — and the divergence survives review because each doc is internally consistent and only the pair is wrong. Cluster by SOURCE OF TRUTH, not by directory.
4. Barrier before the spec chain. Phase 2 → 2.5/2.6 → 3 → 4 stays a FIXED SEQ chain: $spec output feeds the derived index, and §8 TCs feed [mode=sync]. Parallelism lives INSIDE a phase across independent modules — never across these phases.
5. Per-module fan-out is PAR only when the modules are disjoint. Two detected modules that map to ONE Feature Spec share a write target and stay a single task — the same reason Step 0.4 dedups the module list.
6. Every member returns a summary + Full report: path; YOU merge them into the Phase 5 report only after ALL members return, a skipped member counting as returned.

Phase 1: Project Context Sync — Reference Docs + project-config.json (PARALLEL, impact-scoped)

Why this phase exists. docs/project-reference/** and docs/project-config.json are injected into EVERY downstream AI context and route every skill in the framework. When code moves and they do not, the harness keeps teaching a codebase that no longer exists — and nothing else in this skill catches it, because Phases 2-4 only look at docs/specs/**. $scan-all + $project-config do repair them, but they re-derive every doc from zero, which is why they run every 60 days instead of every change. This phase does the same job at diff scope: same no-stale guarantee, small enough to afford after every change.

When to run: ALWAYS, unless Step 0.3 declared a TRUE fast exit. Run it even when every one of Phases 2-4 is skipped.

Scope discipline: verify ONLY what the impact map routes; escalate to a full $scan --target=X when a surgical patch cannot make the doc true again. NEVER regenerate all docs, and NEVER hand-author a full reference doc here — scan owns authoring, this phase owns verification and surgical repair.

Step 1.1: Build the Doc-Impact Map (SEQ — everything below derives from it)

node .claude/scripts/doc-impact-map.cjs --json     # machine-readable (drives the wave)
node .claude/scripts/doc-impact-map.cjs --text     # human-readable (goes in the report)
node .claude/scripts/doc-impact-map.cjs --base=origin/main   # branch-scope instead of working tree

The map routes each changed file to the docs and config sections it can rot, and returns per doc: doc, exists, lastScanned/ageDays, scanTarget (the full-rescan escalation), checks (which verifications apply), changedFiles/addedFiles/deletedFiles, and heuristicOnly. Routing is derived from docs/project-config.json (contextGroups, modules, testing, e2eTesting, styling, designSystem, specRoots) plus change-class rules — never from hardcoded project paths.

Handling the map's output — [BLOCKING] rules:

1. unrouted files are not proof of no impact — they are proof the router had no rule. Classify each by hand: add it to the wave, or record in the report why it carries no doc impact. NEVER let an unrouted file silently pass as fresh.
2. A heuristicOnly doc is a GUESS, not evidence. Verify it like any other, and downgrade to "not impacted" only with a stated reason.
3. Any doc whose exists: false is a MISSING doc, not a fresh one → route to $scan --target=<scanTarget> (or $docs-init when the whole set is absent).
4. If the script is unavailable (older checkout, non-Node host), derive the same map by hand from docs/project-config.json — match changed paths against contextGroups[].pathRegexes → guideDoc/patternsDoc/stylingDoc/designSystemDoc, modules[].pathRegex → project-structure + modules, test/e2e/styling paths → their docs, manifests → tech stack, infra/CI → ports & deployment, .claude/** → inventory counts. Record that the map was manual.

Step 1.2: Declare the Verify Wave (PAR — one message, all members)

Parallel plan: wave 1 = [docs-manager: {doc A}, docs-manager: {cluster B}, docs-manager: project-config.json, …] · SEQ = [Step 1.1 impact map, the Phase 2 → 2.5/2.6 → 3 → 4 spec chain, Phase 5 report] (reason)

Wave-construction rules — the Step 0.6 hazards apply verbatim, plus:

• STRICT one-writer-per-file. docs/project-config.json has exactly ONE owning agent in the wave, always. Two agents merging JSON into the same file is a guaranteed lost update.
• Cluster by SOURCE OF TRUTH, not by directory. README.md + project-structure-reference.md both restate the module/directory map, and CLAUDE.md + docs-index-reference.md + project-structure-reference.md all embed .claude/-derived counts — each such set goes to ONE agent so the numbers cannot diverge inside a single commit.
• Every routed doc appears in exactly one brief. A doc owned by nobody is a silent miss.
• Every member returns its verdict table + Full report: path; merge only after ALL members return.

Step 1.3: Per-Doc Verify Contract (what each wave member actually does)

Verify FIRST, patch NARROW. Run only the checks the map listed for that doc:

Verdict per doc (exactly one, evidence required):

[BLOCKING] Never fabricate freshness. "Looks fine", "probably unchanged", and "the diff was small" are not check results. A doc that was not verified is UNVERIFIED, never FRESH — a false FRESH is worse than no check, because it retires the suspicion that would have caught the drift later.

[BLOCKING] Every PATCHED docs/project-reference/** doc MUST run $prompt-enhance <doc> (default --op=enhance) before the verdict is recorded. These docs are injected into every downstream AI context — a surgical edit that adds correct prose without re-compressing still leaves the doc bloated. $prompt-enhance keeps content as concise as possible while staying valuable enough for AI (caveman compression + attention anchoring), closing the same gap on the narrow patch path that $scan --target=X's own mandatory final step (scan/SKILL.md Final Step) already closes on a full rescan — so a RESCAN REQUIRED doc that escalates to $scan gets it for free and needs no separate call here. Skip ONLY for a single stamp/date/count-only edit, and record the skip reason.

Step 1.4: project-config.json Drift Check (single writer, schema-validated)

Verify ONLY the sections the map flagged. For each:

1. Re-derive from evidence — read the changed files, not the old config value.
2. Surgical merge — add/update entries; NEVER rename, remove, or restructure a top-level section (the $project-config Schema Protection Rules apply here unchanged).
3. Prove every touched pathRegex/path still matches something real — a regex that matches zero files is stale config that silently disables every downstream router that depends on it, and no schema check catches it:

node -e "const c=require('./docs/project-config.json');const {execSync}=require('child_process');const files=execSync('git ls-files',{encoding:'utf8'}).split('\n').filter(Boolean).map(f=>'/'+f);for(const m of c.modules||[]){const re=new RegExp(m.pathRegex,'i');const n=files.filter(f=>re.test(f)).length;console.log((n?'OK  ':'DEAD')+' modules.'+m.name+' -> '+n+' file(s)')}"

4. Validate the schema after the merge:

node -e "const {validateConfig}=require('./.claude/hooks/lib/project-config-schema.cjs');console.log(JSON.stringify(validateConfig(require('./docs/project-config.json')),null,2))"

5. Escalate, don't improvise — a NEW top-level section, a new module class, a new tech stack, or a failed validation means the change is a re-scan, not a patch → run $project-config (and report that it is required if it cannot run in this session).

Step 1.5: README & Project Docs (docs-manager)

Pass the Phase 0 diff context to a docs-manager sub-agent (agent_type="docs-manager") for the prose project docs in the same wave:

• README.md — update if project scope or setup changed (keep under 300 lines)
• docs/project-reference/project-structure-reference.md — update if service architecture or cross-service patterns changed (same agent as README: shared source of truth)

Standalone invocation (not a workflow step) may first delegate 2-4 read-only landscape threads to researcher; as a workflow step, use the Phase 0 diff context directly.

Exclusions unchanged: this agent NEVER owns docs/specs/**, test specs, spec-index/ERD, or derived technical views.

Step 1.6: Stamp Discipline (BLOCKING)

[BLOCKING] An impact-scoped pass MUST NOT touch Last scanned. That stamp is the input to the 60-day full-rescan gate (getStaleReferenceDocs → refreshScanStaleFlag, .claude/hooks/lib/session-init-helpers.cjs:769-810). Moving it from a partial check would buy speed by switching off the net that catches whole-doc rot — the two mechanisms are complementary, not interchangeable.

After any doc in this run WAS fully rescanned, re-evaluate the gate:

node -e "require('./.claude/hooks/lib/session-init-helpers.cjs').refreshScanStaleFlag()"

Step 1.7: Phase 1 Output

Emit the freshness table into the Phase 5 report — one row per routed doc plus one per config section, each with verdict, checks run, and evidence. Docs with RESCAN REQUIRED or UNVERIFIED are carried into Recommendations so the next session inherits the debt explicitly instead of silently.

Phase 2: Business Feature Documentation — Invoke $spec

When 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."

Step 2.1: Determine Create vs Update

Step 2.2: Invoke $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):

• 8-section tech-free structure enforcement
• Diff analysis → section impact mapping
• Codebase analysis (entities, commands, queries, controllers)
• Update impacted sections with evidence
• Bucket INDEX.md catalog row update
• 3-pass verification (evidence audit, domain model, cross-reference)
• Tech-free principles (no implementation details in §1–§7; evidence carriers in §8 + [Source:] only)

Step 2.3: Review $spec Output

1. Updated sections align with triage's section impact mapping
2. No sections missed that triage flagged as impacted
3. Gaps found → re-invoke $spec for missed sections

Step 2.4: Code↔Spec Sync-Verify (final pass — runs because docs-update is last in every sequence)

Purpose: 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:

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-sync mode is added — this responsibility lives inside docs-update's existing final pass.

Phase 2.5: Derived Index / ERD Refresh (OPTIONAL — spec-index)

[SINGLE-HOME] There is no separate "engineering spec bundle". The canonical artifact is the 8-section Feature Spec updated in Phase 2. spec-index is repurposed to regenerate only the DERIVED bucket INDEX.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:

• Only docs/, .claude/, or config files changed
• No Feature Spec under docs/specs/{Bucket}/ was touched
• Phase 2 was skipped (no feature impact)
• The bucket maintains no derived index/ERD, OR project-config.json contains "spec_discovery_update": false
• spec already refreshed INDEX.md in Phase 2 (no separate refresh needed)

Step 2.5.1: Resolve the Bucket

• Map the changed services to an App Bucket using the canonical table in docs/project-reference/spec-system-reference.md → App Bucket Mapping.
• Confirm docs/specs/{Bucket}/ holds the updated Feature Spec(s).

Step 2.5.2: Invoke spec-index (Derived Index Mode)

$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.

Step 2.5.3: Verify Refresh Complete

• Confirm INDEX.md rows match the current set of Feature Specs (no dangling links, no missing capabilities).
• Confirm the DERIVED banner + regenerate date are present.
• Report: "Derived index refreshed: {Bucket} — {N} capabilities catalogued".

Separation of concerns: docs-update orchestrates — passes the bucket scope to spec-index. NEVER hand-edits the derived index, and NEVER recreates M##/A-E artifacts (retired).

Phase 2.6: Derived Technical View Refresh (OPTIONAL — tech-spec)

[SINGLE-HOME] The derived technical root comes from docs/project-config.json → specRoots.technical.path. $tech-spec owns that output; docs-update routes and verifies it, but never hand-edits a generated view.

When to run: The impact map or source anchors show that a code/test change affects the configured technical tree. Technical-only framework tooling changes may still need a generator freshness check.

When to skip: The change is docs/config-only, no technical source or annotation is affected, the technical scan is not configured for this project, or the derived tree is demonstrably unaffected. Record the evidence and skip reason in the Phase 5 report; an absent techSpecScan is not a reason to invent a project-specific annotation pattern.

Step 2.6.1: Resolve the Technical Scope

• Resolve specRoots.technical.path and any techSpecScan settings from project configuration.
• The generator's CLI owns a full configured-root generation mode and a read-only --check mode. Do not route to unsupported --scope or --all arguments.
• If a technical source change affects the derived tree, invoke $tech-spec with the component context and let that skill determine its mechanical output. Keep this router's write set empty.

Step 2.6.2: Invoke and Verify

npm run tech-spec:generate

Equivalent standalone invocation:

node .claude/skills/tech-spec/scripts/generate-tech-specs.mjs

For a read-only gate, use npm run tech-spec:check or the direct --check command. If the project does not declare techSpecScan, the sync orchestrator records an explicit SKIP (not configured); direct generator invocation remains fail-closed so a malformed declared contract cannot look fresh.

Verify the result through $tech-spec: every emitted view has the DERIVED banner, the configured technical root contains no retired artifacts, anchors are traceable, and a second unchanged check is byte-stable. Report output paths, files written/removed/unchanged, and the freshness verdict.

Phase 3: Test Specifications — Invoke $spec [mode=tests]

When to run: New business-visible functionality added OR existing business-visible behavior changed. Technical-only changes with no changed user/QC-visible outcome produce no business Section 8 edits; route any technical coverage need to tests and $tech-spec for the derived technical view.

When to skip: Changes purely cosmetic (styling, comments, docs-only) with no behavioral impact.

Step 3.1: Determine TC Mode

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.

Step 3.2: Invoke $spec [mode=tests]

$spec [mode=tests] Mode: {detected mode}.
Modules: {detected modules}.
Changed files: {list from triage}.
Business-visible functionality detected: {new or changed user/QC-visible outcomes from diff analysis}.

What $spec [mode=tests] handles (DO NOT duplicate here):

• 5 modes: TDD-first, implement-first, update, sync, from-integration-tests
• TC-{FEATURE}-{NNN} format with decade-based numbering
• Interactive TC review (ask the user directly)
• Cross-cutting categories: authorization, seed data, performance, data migration
• Phase-mapped coverage (plan phases → TCs)
• Graph context analysis for cross-service impact
• Evidence verification per TC
• Write to feature doc Section 8 (canonical business TC registry)

Step 3.3: Review $spec [mode=tests] Output

1. New TCs cover all new business-visible functionality from triage
2. TC IDs don't collide with existing ones
3. Evidence fields populated (not template placeholders)

Phase 4: Test Spec ↔ Test Code Sync — Invoke $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.

Step 4.1: Invoke $spec [mode=sync]

$spec [mode=sync] Sync test specs for capabilities: {detected features}.
Direction: forward (Feature Spec §8 Test Specifications → executing test code).
Updated TCs from Phase 3: {list of new/changed TC IDs}.

What $spec [mode=sync] handles (DO NOT duplicate here):

• Forward/reverse sync: §8 Test Specifications ↔ executing test code
• 2-way comparison: Feature Spec §8 vs test code (code is the technical source of truth)
• Test cross-reference (configured test-spec annotation key TestSpec across all executing test tiers and the per-TC CoveredBy: field; legacy IntegrationTest: is migration input only)

The retired QA dashboards (docs/specs/README.md, docs/specs/PRIORITY-INDEX.md) and the hand-maintained A-E/M## engineering tree no longer exist — §8 is the canonical business TC registry. Derived aids are the bucket INDEX.md count (Phase 2.5) and the regenerable technical view under specRoots.technical.path (Phase 2.6).

Step 4.2: Review Sync Results

1. All new TCs from Phase 3 are reflected in test code (or flagged Untested with rationale).
2. No orphaned TCs (referenced by test code's TestSpec annotation but absent from §8).

Section Ownership Reference

Which skill owns which doc sections — docs-update delegates only, NEVER writes directly:

Phase 5: Summary Report

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 Context Sync (impact-scoped freshness):**

Impact map: {N} changed files → {D} docs, {S} config sections, {U} unrouted ({map source: working tree / last commit / branch})

| Reference doc | Verdict | Checks run | Evidence / action |
| ------------- | ------- | ---------- | ----------------- |
| {doc} | FRESH / PATCHED / RESCAN REQUIRED / UNVERIFIED | {claims, coverage, counts, …} | {what was compared; sections patched; scan target queued} |

| project-config.json section | Verdict | Evidence / action |
| --------------------------- | ------- | ----------------- |
| {section} | FRESH / PATCHED / RESCAN REQUIRED / UNVERIFIED | {re-derived from …; schema validation result; dead pathRegex found} |

- Unrouted files classified: {file → why no doc impact}
- README / project docs: {Updated/Skipped}: {reason}
- Stamps: {docs given `Last verified`} · {docs fully rescanned and given `Last scanned`} · staleness flag refreshed: {yes/no}

**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}

Decision Matrix: When to Use docs-update vs Direct Skill

Additional Requests

Pass caller context via $ARGUMENTS to skip redundant triage or narrow scope:

<additional_requests> $ARGUMENTS </additional_requests>

Escalation: When docs-update Is Not Enough

[BLOCKING] Create ALL 8 tasks via task tracking BEFORE 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/2.6 -> 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 task in_progress; AFTER each step, mark task completed with 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:line proof 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 out

Truncated - read the full file at https://github.com/duc01226/easy-claude/blob/e46c5f1a56e43f9a04e7704ede06824623450bf6/.agents/skills/docs-update/SKILL.md.