跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

diff-driven-docs

Use when a BUILD phase completes, a commit is staged, or a PR is about to be created, and the diff has not yet been reflected in documentation. Also use when the user says "update docs", "sync docs", "document this", or asks whether documentation is up to date.

romiluz13 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add romiluz13/cc10x --skill diff-driven-docs

技能说明


name: diff-driven-docs description: >- Use when a BUILD phase completes, a commit is staged, or a PR is about to be created, and the diff has not yet been reflected in documentation. Also use when the user says "update docs", "sync docs", "document this", or asks whether documentation is up to date. allowed-tools: Read, Edit, Write, Bash, Grep, Glob

diff-driven-docs

Overview

Stale documentation is worse than no documentation — it actively misleads contributors, users, and future maintainers. Run the Impact Classifier on the diff across the four layers (business, technical, audit, glossary); write only what a layer's verdict requires.

Impact Classifier

Run this classifier before any doc work. Use it to determine which layers to evaluate and which to skip.

Diff CharacteristicBusiness LayerTechnical LayerAudit LayerGlossary Layer
Internal utility, helper, or type change onlySKIPCHECKSKIPSKIP
Test addition with no new patternSKIPSKIPSKIPSKIP
Style / formatting changeSKIPSKIPSKIPSKIP
Dependency version bump (no API change)SKIPSKIPSKIPSKIP
Routine bug fix (existing behavior corrected)SKIPCHECKSKIPSKIP
Simple refactor (behavior unchanged)SKIPCHECK if signatures changedSKIPSKIP
New exported function / hook / componentSKIPCHECKCHECKSKIP
New page or routeCHECKCHECKCHECKCHECK
Architectural pattern introducedSKIPCHECKCREATECHECK
Technology choice madeSKIPCHECKCREATECHECK
Breaking change to public APICHECKCHECKCREATECHECK
Permission or role changeCHECKCHECKCHECKSKIP
Security or compliance impactCHECKCHECKCREATE or UPDATESKIP
Domain term resolved or sharpened during the workflowSKIPSKIPSKIPCHECK

SKIP business docs if: no user-facing surface changed; only internal utils, types, or tests were modified.

ALWAYS check technical docs when hooks, components, migrations, schema, routes, or exported library APIs changed.

CREATE an audit doc if: an architectural decision was made, a new pattern was introduced, a non-obvious tradeoff was accepted, or a team member six months from now would ask "why did we do it this way?"

CHECK glossary docs if: a domain term was resolved, sharpened, or found to contradict the code during a BUILD/PLAN/DEBUG workflow. The glossary layer is written only by designated shaping phases (planner, exploration DESIGN mode, doc-syncer) via cc10x:domain-modeling; builders emit proposals. See the Glossary Layer section below.

If all four layers are SKIP, set IMPACT_LEVEL: none and emit a SKIPPED contract immediately without opening any doc files.

The Four Layers

Business Layer

User-facing guides, admin documentation, and feature descriptions. Business docs describe what users and administrators can do — not how the system works internally.

  • Scope: user guides, admin guides, settings references, feature descriptions, permissions documentation
  • Update trigger: new or changed user-facing behavior, new page or route, permission change, config option that affects user behavior
  • What to write: describe the feature from the user's perspective; do not expose internal implementation details

Technical Layer

Hooks reference, components catalog, schema documentation, architecture notes, and JSDoc on exported APIs. Technical docs describe how the system is built — for developers working on the codebase.

  • Scope: hooks reference, components catalog, API reference, edge function reference, database schema docs, environment variable docs, architecture notes
  • Update trigger: any exported function, hook, or component whose signature was added or changed; any migration or schema change; any new route or page
  • What to write: name, file path, description, signature, params, return value, key behaviors; for component-based frameworks, document component inputs (props, arguments, or slots)

Audit Layer

Decision records capturing what changed, why, alternatives considered, and impact. Audit docs are written for future contributors who need to understand the reasoning behind a decision.

  • Scope: docs/adr/ (canonical, NNNN-numbered; legacy docs/decisions/ date-named files migrated lazily on touch), compliance notes, migration guides for breaking changes
  • Update trigger: new architectural pattern, technology choice, non-obvious tradeoff, breaking change, security or compliance impact
  • What to write: structured record following the four-section format below (or a single-paragraph ADR for simple decisions, per cc10x:domain-modeling/ADR-FORMAT.md)
  • Dedup rule: if a decision exists in both docs/decisions/ and docs/adr/, the docs/adr/ version wins; delete the legacy duplicate — two live copies diverge, and readers can't tell which is authoritative

Glossary Layer

CONTEXT.md at the repo root — the project's domain language (terms and their meanings, no implementation details). Maintained inline by shaping phases (planner, exploration DESIGN mode, doc-syncer) via cc10x:domain-modeling.

  • Scope: CONTEXT.md (root), or per-context CONTEXT.md files if CONTEXT-MAP.md exists
  • Update trigger: a domain term is resolved, sharpened, or found to contradict the code during a BUILD/PLAN/DEBUG workflow
  • What to write: append-only glossary entries using cc10x:domain-modeling/CONTEXT-FORMAT.md (term, one-two sentence definition, _Avoid_ aliases)
  • Do NOT write implementation details, specs, or scratch notes in CONTEXT.md — it is a glossary only

Audit Doc Guidance

When to Create vs. Update

SKIP verdicts are owned by the Impact Classifier table above.

CREATE new when:

  • A pattern is introduced for the first time in this codebase
  • An architectural decision is made that future
阅读完整来源 ↗