thrashr888 5-Style Documentation System
Use this skill when creating project documentation, planning features, or organizing technical decisions.
Agent-Ready Documentation
Document intent, constraints, and rationale that code alone cannot reveal. Agents can inspect implementation details, but they cannot infer requirements discussed in meetings, external contracts, business rules, or the reason a non-obvious decision was made. Put those facts in the narrowest durable artifact:
- requirements and plans define observable acceptance criteria and non-goals;
- specs record invariants, external constraints, and architectural boundaries;
- ADRs record a significant decision and its rationale; and
- skills record a repeatable implementation or verification workflow.
Do not write documentation that merely paraphrases code. Before publishing a document, ask whether a future engineer or agent could learn why this behavior exists and how to prove it still meets its constraints.
The 5 Documentation Styles
| Style | Purpose | Location | Update Trigger |
|---|---|---|---|
| 1. Plan Mode | Deep exploration before coding | plans/ |
Per feature |
| 2. Issues | Track work across sessions | .beads/ or GH |
Throughout feature |
| 3. Evergreen Specs | System truth ("how it works") | specs/ |
Architecture changes |
| 4. Skills | Agent guides ("how to implement") | .claude/skills/ |
Pattern changes |
| 5. User Docs | Human communication | README, CLAUDE.md | Major features |
When to Use Each Style
Style 1: Plan Mode (plans/)
Purpose: Explore and design before coding
When to use:
- Starting a non-trivial feature
- Making architectural decisions
- Complex refactoring
File naming: plans/YYYY-MM-DD-feature-name.md
Template: See references/plan-template.md
Style 2: Issues (.beads/ or GitHub)
Purpose: Track work items and dependencies
When to use:
- Work spans multiple sessions
- Feature has dependencies
- Need to track blockers
Commands:
bd create --title="..." --type=task|bug|feature --priority=2
bd update <id> --status=in_progress
bd close <id>
Style 3: Specs (specs/)
Purpose: Document architectural truth - WHAT the system does
When to use:
- Architecture changes
- New subsystems added
- Core patterns established
Characteristics:
- Declarative, not prescriptive
- Evergreen (rarely becomes stale)
- Describes intent, constraints, and invariants
- States the rationale behind non-obvious boundaries
Template: See references/spec-template.md
Style 4: Skills (.claude/skills/)
Purpose: Guide agents on HOW to implement
When to use:
- New implementation patterns
- Workflow documentation
- Agent guidance needed
Characteristics:
- Prescriptive (step-by-step)
- Code examples
- Tool allowlists
Template: See references/skill-template.md
Style 5: User Docs (README, CLAUDE.md)
Purpose: Human-facing communication
When to use:
- Public-facing changes
- Getting started guides
- API documentation
Files:
README.md: Project overview, installationCLAUDE.md: Agent instructionsAGENTS.md: Compiled agent instructions
Decision Framework
| Situation | Action |
|---|---|
| Starting new feature | Enter plan mode → write to plans/ |
| Feature spans sessions | Create beads issue |
| New architectural pattern | Update spec in specs/ |
| New implementation pattern | Update skill in .claude/skills/ |
| Public-facing change | Update README.md |
| Agent guidance needed | Update CLAUDE.md |
Additional Templates
For specific use cases:
- RFC (
references/rfc-template.md): Formal proposals needing team input - ADR (
references/adr-template.md): Architecture decision records - Bug Report (
references/bug-report-template.md): Bug documentation - Feature Request (
references/feature-request-template.md): Feature proposals - Pull Request (
references/pull-request-template.md): PR descriptions
Anti-Patterns
DON'T:
- Write RFC-style docs that get stale ("We plan to add X")
- Document temporary decisions in specs (use issues)
- Put implementation details in specs (use skills)
- Put architectural constraints in skills (use specs)
DO:
- Keep specs declarative and evergreen
- Keep skills prescriptive and code-focused
- Track multi-session work in issues
- Update docs when patterns change
Resources
All templates available in references/:
plan-template.md- Plan mode templatespec-template.md- Evergreen spec templateskill-template.md- Skill document templaterfc-template.md- RFC templateadr-template.md- ADR templatebug-report-template.md- Bug report templatefeature-request-template.md- Feature request templatepull-request-template.md- PR description template