메뉴
Use when reviewing documentation quality, when establishing README and changelog standards, when preventing doc rot, when in-code comments duplicate code instead of explaining intent, or when subdirectories of a repo have no documentation entry point.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | documentation-hygiene |
| description | Use when reviewing documentation quality, when establishing README and changelog standards, when preventing doc rot, when in-code comments duplicate code instead of explaining intent, or when subdirectories of a repo have no documentation entry point. |
Define the project's documentation contract — what gets documented, where it lives, how it stays current — before docs rot. Output is .forge/docs-policy.md: README standard per repo and subdirectory, in-code comment policy (WHY not WHAT), doc-rot prevention rules (dates, code links, generated docs), public-vs-internal doc split, and changelog discipline. Pairs with code-review-and-quality (review enforces the policy) and shipping-and-launch (CHANGELOG updated per release).
| Thought | Reality |
|---|---|
| "The code is self-documenting" | Code shows what, not why. Two months later the original author cannot reconstruct why. |
| "Docs get stale anyway, why bother" | Dated docs with code links rot slower than undated docs. The half-life of a comment near its code is years; far from its code, weeks. |
| "README is enough" | README without subdirectory docs creates a treasure hunt for every new contributor. |
| "We'll document before launch" | You won't. And if you do, the doc will be wrong because you'll write it from memory. |
| "Comments are noise" | Comments that explain WHY are signal. Comments that restate the code are noise. The fix is to write the right comments, not to delete all comments. |
| "Generated docs are good enough" | Generated docs answer "what does this function take" — not "when should I call it" or "what changes if I don't." |
// increment i by 1 next to i++In .forge/docs-policy.md, the README contract for every repo top-level:
# <project name>
One-sentence description.
## What this is
2-3 sentence description.
## Status
Stable / Beta / Experimental — and what that means for breaking changes.
## Quick start
The single command (or 3) that gets a developer running.
## Where things live
Pointers to subdirectory READMEs.
## Contributing
How to propose a change. Link to CONTRIBUTING.md if it exists.
## License
SPDX identifier.
For every subdirectory with >5 files: a README that answers "what is in here, why is it here, who owns it."
The rule: explain WHY, not WHAT.
| Bad (WHAT) | Good (WHY) |
|---|---|
// increment i | // skip the sentinel row at index 0 |
// loop over users | // fan-out concurrency capped at 5 to respect upstream rate limit |
// returns null | // returns null when the user has been soft-deleted; callers must filter |
// magic number 86400 | // 86400 = 24h in seconds; matches the auth token TTL in config.ts |
Comments are required for:
// workaround for issue-1234 in upstream-lib v3.x)// invariant: ordersByUser is updated by users.ts:create())Comments are forbidden for:
Every doc carries:
<!-- updated: YYYY-MM-DD --> footer)main, not commit hashes) — if the link 404s, CI failsPrefer generated docs (typedoc, rustdoc, godoc) for API reference. Hand-written docs for concepts, workflows, and decisions (ADRs).
In .forge/docs-policy.md:
api-design for endpoint docs)CONTRIBUTING.md, ADRs, runbooks)Each doc has a banner indicating its tier.
Follow Keep a Changelog: one entry per user-visible change, grouped by Added, Changed, Deprecated, Removed, Fixed, Security. Breaking changes flagged with BREAKING: prefix. Refactors don't get entries unless they affect performance, security, or behavior. Updated in the PR that makes the change, not at release time.
CI job runs weekly:
Failures open tickets, not block CI (these are guideposts, not gates).
.forge/docs-policy.md written^// .*[a-zA-Z(] for obvious patterns)Use when implementing features or fixing bugs test-first, when user mentions "red-green-refactor", when test discipline is required for a specific task, when incremental-implementation needs TDD enforcement, or when a behavior change needs a failing test before any code is written.
Use when .forge/prd.md exists and the system needs a structural design before task breakdown, when modules will be implemented in parallel and need interface contracts to prevent integration failures, or when non-obvious technical decisions need to be recorded for future reference.
Use when .forge/prd.md and .forge/architecture.md exist and the work needs to be decomposed before implementation, when sizing tasks for a sprint, when mapping dependencies between modules, or when a critical path needs to be identified before parallel work begins.
Use when user wants to write a spec, create a PRD, or plan a new feature before implementation begins, when .forge/idea-brief.md exists and is ready to formalize, when requirements need to be captured before architecture or planning, or when a feature's scope and acceptance criteria need to be documented.
Use when creating a new forge-skill, editing an existing skill, when planning to contribute to forge-skills, when a session has produced a one-off prompt that should be promoted to a skill, or when verifying a skill works before deployment.
Use when checking if .forge/ artifacts are stale after a change to requirements, architecture, or any upstream artifact. Use before running /build, /review, or /ship to confirm the artifact chain is consistent. Use when the user says "is anything out of date" or "what needs to be regenerated".