From docs-cockpit
Refresh an existing docs-cockpit: diagnose stale anchors, re-sync changed specs, answer status/progress questions, run health checks, and render fixes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/docs-cockpit:docs-cockpit-rebuildThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**The 5-phase workflow for diagnosing and refreshing an existing module ↔ subtask ↔ spec/plan/RFC association system — and for answering "how is the project doing" along the way.**
The 5-phase workflow for diagnosing and refreshing an existing module ↔ subtask ↔ spec/plan/RFC association system — and for answering "how is the project doing" along the way.
docs-cockpit-build creates the association system; this skill keeps it true. Anchors are line ranges and section headings into living files — every refactor moves code, every spec revision moves sections, and an anchor that pointed at the right lines last sprint can silently point at garbage today. The same principle that governs build governs rebuild, only more urgently: a wrong anchor is worse than a missing anchor. A drifted anchor sends the user to irrelevant content while looking authoritative, which destroys trust in the entire dashboard. So rebuild's job is precision maintenance: re-verify everything, re-infer only what broke, and touch nothing that is still accurate.
Both skills share the same four atomic methods in references/association-method.md — they differ in direction and scope:
If no association exists at all (no docs: / subtasks anchors anywhere), stop and hand off to docs-cockpit-build — diagnosing an empty system is not a rebuild.
「体检一下」「全面体检」「健康检查」 / "health check" / "checkup" trigger a checkup run: execute Phase 1–2, present the three-part report, and STOP — the report IS the deliverable, with the same endpoint semantics as pure status queries ending at Phase 1. Treatment (Phase 3–4) starts only if the user then confirms buckets. Mode selection: the request contains 「深度」/「全面」/ "deep" / "full" → deep mode (all nine departments, full anchor-verdict pass); otherwise quick mode. Methodology, thresholds, and templates: references/health-check.md.
This skill is the orchestration layer — it tells you which phase to run when. The details live in references (do not restate them; read them when the phase needs them):
| Reference | Holds | Used by |
|---|---|---|
references/association-method.md | the 4 atomic methods (discovery / reasoning / dry-run / highlight) | Phase 2–3 |
references/schema.md | frontmatter fields · subtask forms · code/doc anchor formats | Phase 4 |
references/health-check.md | nine-department checkup methodology · three-part report template · five-bucket triage · HEALTH.md writing rules | Phase 2 (checkup report), 3–4 (bucket landing) |
docs/state.json | machine-readable current state (input, not a doc to edit) | Phase 1 |
Default scope is all existing anchors in the project. The user can narrow it ("only M07", "only docs touched by this refactor"); say so explicitly in Phase 2's verdict table if scoped down.
docs/state.json. Key fields: modules[].status / modules[].progress / modules[].subtasks[] (per-subtask status / done / code+doc anchors with exists flags), and issues[] (structured validator output). Cross-read the module MDs when project.lastBuild looks older than recent repo activity — state.json is a build artifact and can itself be stale. From this, answer the narrative questions directly: what's blocked and on what, which sprint is how far along, which modules haven't moved.docs/state.json (top-level shape: project / systemDocs / modules / concepts / warnings / issues).
Narrative shape (for status answers):Sprint M1.2 · 3/5 modules on track · 1 blocked. M07 (60%, in-progress): 2/4 subtasks done, latest anchor all ✅. M09 (blocked): waiting on RFC-004 decision — see issues[]. Next action: unblock M09 or pull M11 forward.
Order: sprint overview → per-module status (group by status, blocked first) → concrete blockers from issues[] → suggested next action.
Pure status queries END at this phase. If the user asked "项目进度怎么样" / "what's blocked" / "sprint progress" and nothing suggests drift, Phase 1's narrative IS the deliverable — no lint, no anchor verification, no file edits. Only proceed to Phase 2 when the user reports drift ("关联乱了", "重构后失效"), when Phase 1 surfaces evidence of it (anchors with exists: false, issues[] about anchors), or when the user explicitly asks for a re-sync.
docs-cockpit lint for the dead-rule layer: schema violations, missing ids, and the subtask-missing-anchors list of 0-anchor subtasks. (b) Apply Method 3 (dry-run) to re-verify ALL existing anchors — Read each anchor's exact target slice (offset/limit for :lines, heading scan for #§N) and compare against the owning subtask's title. Assign each anchor one of the 4 verdicts: ✅ accurate / ⚠️ partial / ❌ wrong / ❓ missing.references/association-method.md).Scale note: if existing anchors > 30, don't brute-force every one. Run lint first (free, catches missing/dead files), then prioritize dry-run on anchors whose target files changed recently (git log / user-named refactor scope), batch the rest and report progress per batch.
Verdict presentation format (example):
【诊断 7/23】 M03 「Render Engine」 · subtask M03-S2 「drawer 内联渲染 linked docs」
现存 anchor : @docs:docs/plans/2026-04-12-m03-render-plan.md#§3.1
预演 verdict: ⚠️ partial —— §3.1 标题还在,但 drawer 内联逻辑在 v0.18 重排后挪到了 §3.4
处理 : → Phase 3 重推理(候选 §3.4)
End of phase · checkup consolidation(复查呈报). Phase 1–2 are this skill's recheck(复查): consolidate their diagnostic output per references/health-check.md into a checkup report before any treatment:
docs/HEALTH.md — frontmatter per references/schema.md · health-report schema. RX ids are stable and monotonic: resolved prescriptions are removed (their numbers never reused), unresolved ones keep their original id, new ones continue from the last max.# TODO rather than forcing the nearest section. ✅ accurate anchors are not re-inferred and not touched — re-deriving them wastes effort and risks churn.references/association-method.md).subtasks: object array vs body @code: / @docs: inline — exact syntax per references/schema.md; never mix forms in one doc. Destructive changes need the user's ruling first: deleting an anchor outright, changing a module/subtask id, retargeting to a different doc kind — propose, explain why, wait. Range adjustments within the same file (⚠️ partial verdicts) are auto-applicable; all other structural changes (id rename, sprint reassignment, doc-kind change, anchor deletion) require the user's ruling. After editing, Read each changed subtask block once to confirm the written anchor matches the proposal — don't rely on Edit's success alone.references/schema.md (subtask forms · anchor formats).What "minimal diff" looks like (the only changed bytes are the drifted anchor):
- - [ ] drawer 内联渲染 linked docs @docs:docs/plans/2026-04-12-m03-render-plan.md#§3.1
+ - [ ] drawer 内联渲染 linked docs @docs:docs/plans/2026-04-12-m03-render-plan.md#§3.4
Checkup prescription landing(处方→subtask 闭环). Bucket decisions confirmed at the end of Phase 2 land here, with the same rules as build Phase 6:
sprint — write the prescription as a subtask (title per schema.md's 4 rules) carrying a @code: anchor at the problem location, under the module named by the prescription's module field; no owning module → ask the user before creating a dedicated health-debt module(「健康债」). Sync the sprint-plan in_scope.backlog — draft a plan doc(file naming per references/schema.md · 文件命名约定)with the prescription's anchors in its evidence section.accepted — record in docs/HEALTH.md accepted_debts(item / reason / review date — ledger rules per health-check.md).watch — stays in docs/HEALTH.md prescriptions with bucket: watch; the next checkup verifies these first.now — treat on the spot in this phase(edit + docs-cockpit render verify).docs-cockpit render and read the issue output. Any ❌/⚠️ traced to this rebuild's edits → fix (loop back to the relevant phase for that item) and re-render. Pre-existing unrelated warnings: surface to the user, don't block on them.docs/index.html + docs/state.json, 0 warnings from this rebuild's changes.Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub guohao1020/docs-cockpit --plugin docs-cockpit