Doc

Doc Skill

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Generate and validate documentation for any project. --mode selects the artifact family — the default mode handles code/API docs and code-maps; --mode=readme generates a gold-standard README; --mode=oss scaffolds and audits the open-source doc pack.

Modes

Mode routing (absorbed skills):

When invoked with --mode=readme or --mode=oss, read the corresponding reference above and follow its workflow verbatim. The default-mode steps below apply only when no mode (or the implied code-docs mode) is selected.

Execution Steps (default mode — code/API docs)

Given /doc [command] [target]:

Step 1: Detect Project Type

# Check for indicators
ls package.json pyproject.toml go.mod Cargo.toml 2>/dev/null

# Check for existing docs
ls -d docs/ doc/ documentation/ 2>/dev/null

Classify as:

• CODING: Has source code, needs API docs
• INFORMATIONAL: Primarily documentation (wiki, knowledge base)
• OPS: Infrastructure, deployment, runbooks

Step 2: Execute Command

discover - Find undocumented features:

# Find public functions without docstrings (Python)
grep -r "^def " --include="*.py" | grep -v '"""' | head -20

# Find exported functions without comments (Go)
grep -r "^func [A-Z]" --include="*.go" | head -20

coverage - Check documentation coverage:

# Count documented vs undocumented
TOTAL=$(grep -r "^def \|^func \|^class " --include="*.py" --include="*.go" | wc -l)
DOCUMENTED=$(grep -r '"""' --include="*.py" | wc -l)
echo "Coverage: $DOCUMENTED / $TOTAL"

gen [feature] - Generate documentation: 1. Read the code for the feature 2. Understand what it does 3. Generate appropriate documentation 4. Write to docs/ directory

all - Update all documentation: 1. Run discover to find gaps 2. Generate docs for each undocumented feature 3. Validate existing docs are current

Step 3: Generate Documentation

When generating docs, include:

For Functions/Methods:

## function_name

**Purpose:** What it does

**Parameters:**
- `param1` (type): Description
- `param2` (type): Description

**Returns:** What it returns

**Example:**

result = function_name(arg1, arg2)

**Notes:** Any important caveats

For Classes:

## ClassName

**Purpose:** What this class represents

**Attributes:**
- `attr1`: Description
- `attr2`: Description

**Methods:**
- `method1()`: What it does
- `method2()`: What it does

**Usage:**

obj = ClassName() obj.method1()

Step 4: Create Code-Map (if requested)

Write to: docs/code-map/

# Code Map: <Project>

## Overview
<High-level architecture>

## Directory Structure

src/ ├── module1/ # Purpose ├── module2/ # Purpose └── utils/ # Shared utilities

## Key Components

### Module 1
- **Purpose:** What it does
- **Entry point:** `main.py`
- **Key files:** `handler.py`, `models.py`

### Module 2
...

## Data Flow
<How data moves through the system>

## Dependencies
<External dependencies and why>

Step 5: Validate Documentation

Check for:

• Out-of-date docs (code changed, docs didn't)
• Missing sections (no examples, no parameters)
• Broken links
• Inconsistent formatting

Step 6: Write Report

Write to: .agents/doc/YYYY-MM-DD-<target>.md

# Documentation Report: <Target>

**Date:** YYYY-MM-DD
**Project Type:** <CODING/INFORMATIONAL/OPS>

## Coverage
- Total documentable items: <count>
- Documented: <count>
- Coverage: <percentage>%

## Generated
- <list of docs generated>

## Gaps Found
- <undocumented item 1>
- <undocumented item 2>

## Validation Issues
- <issue 1>
- <issue 2>

## Next Steps
- [ ] Document remaining gaps
- [ ] Fix validation issues

Step 7: Report to User

Tell the user: 1. Documentation coverage percentage 2. Docs generated/updated 3. Gaps remaining 4. Location of report

Key Rules

• Detect project type first - approach varies
• Generate meaningful docs - not just stubs
• Include examples - always show usage
• Validate existing - docs can go stale
• Write the report - track coverage over time

Commands Summary

Examples

Generating API Documentation

User says: /doc gen authentication

What happens: 1. Agent detects project type by checking for package.json and finding Node.js project 2. Agent searches codebase for authentication-related functions using grep 3. Agent reads authentication module files to understand implementation 4. Agent generates documentation with purpose, parameters, returns, and usage examples 5. Agent writes to docs/api/authentication.md with code samples 6. Agent validates generated docs match actual function signatures

Result: Complete API documentation created for authentication module with working code examples.

Checking Documentation Coverage

User says: /doc coverage

What happens: 1. Agent detects Python project from pyproject.toml 2. Agent counts total functions/classes with grep -r "^def \|^class " 3. Agent counts documented items by searching for docstrings (""") 4. Agent calculates coverage: 45/67 items = 67% coverage 5. Agent writes report to .agents/doc/2026-02-13-coverage.md 6. Agent lists 22 undocumented functions as gaps

Result: Documentation coverage report shows 67% coverage with specific list of 22 functions needing docs.

Troubleshooting

Reference Documents

• references/doc.feature — Executable spec: detect project type, generate type-appropriate docs from the repo, validate existing docs against source (soc-qk4b)
• references/readme.feature — Executable spec (--mode=readme): mode detection, problem-first lead, trust block near install, collapse-don't-delete depth, the council gate, anti-pattern detection (soc-qk4b)
• references/oss-docs.feature — Executable spec (--mode=oss): audit existing/missing OSS docs, scaffold missing without overwrite, project-type-tailored (soc-qk4b)

• references/readme-craft.md — --mode=readme: the 8 gold-standard README patterns, interview, generation structure, council validation, anti-pattern table
• references/oss-pack.md — --mode=oss: audit + scaffold the OSS doc pack (CONTRIBUTING/CHANGELOG/AGENTS.md), project-type templates
• references/oss-documentation-tiers.md — OSS doc tier definitions (core/standard/enhanced)
• references/oss-project-types.md — Per-type OSS scaffolding templates (cli/operator/service/library/helm)
• references/oss-beads-patterns.md — AGENTS.md beads-tracker patterns for OSS projects
• references/generation-templates.md
• references/prose-and-report-workmanship.md
• references/project-types.md
• references/validation-rules.md
• references/de-slopify.md — Remove AI writing artifacts from docs
• references/architecture-report.md — Generate technical architecture documents

<!-- TOC: Core | Prompt | Quick Start | Modes | Anti-Patterns | Subagent | References -->

Codebase Report

Core Insight: Understanding is ephemeral. Documents survive context compaction.

The Problem

You explore a codebase, build a mental model, then context compacts. This skill produces reusable artifacts that survive.

Differs from codebase-archaeology: Archaeology = understanding. This = producing a document.

---

THE EXACT PROMPT

Produce a Comprehensive Technical Architecture Report for this codebase:

1. Executive summary (what is it, key stats)
2. Entry points (main, routes, handlers)
3. Key types (3-5 core domain objects)
4. Data flow (input → processing → output)
5. External dependencies (DBs, APIs, critical libs)
6. Configuration (env, files, CLI, precedence)
7. Test infrastructure

Include file:line references. Output as markdown I can reference later.

---

Quick Start

# Option 1: Auto-scaffold (fills what it can detect)
./scripts/scaffold-report.py /path/to/project > ARCHITECTURE.md

# Option 2: Manual exploration
cat README.md AGENTS.md 2>/dev/null | head -200
ls src/ lib/ cmd/ pkg/ 2>/dev/null
rg "fn main|func main|if __name__" --type-add 'all:*.*' -l | head -5

# Then fill template from the structure below

---

Report Modes

Quick Scan (Minimal)

Quick architecture overview:
- What is it? (1 sentence)
- Entry points (list)
- 3 key types
- Main data flow (1 diagram)
Keep under 150 lines.

---

Output Structure

# [Project] - Technical Architecture Report

## Executive Summary
[What + stats in 3 lines]

## Entry Points
| Entry | Location | Purpose |
|-------|----------|---------|

## Key Types
| Type | Location | Purpose |
|------|----------|---------|

## Data Flow
[ASCII diagram + 2-sentence description]

## External Dependencies
| Dependency | Purpose | Critical? |
|------------|---------|-----------|

## Configuration
| Source | Priority | Example |
|--------|----------|---------|

## Test Infrastructure
| Type | Location | Count |
|------|----------|-------|

---

Delegation Pattern

For large codebases, delegate exploration:

Use the codebase-explorer subagent to explore this codebase.
Return structured findings, then I'll compile the final report.

The subagent explores in read-only mode and returns findings in report-ready format.

---

Anti-Patterns

---

Integration

With Hooks

Auto-generate report stub on new project:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "if echo \"$TOOL_INPUT\" | grep -q 'git clone'; then ./scripts/scaffold-report.py . > ARCHITECTURE.md; fi"
      }]
    }]
  }
}

With Other Skills

---

References

Scripts

Subagents

Example Architecture Reports

Example 1: beads_rust (CLI Tool)

Real report from a local-first issue tracker:

# beads_rust - Technical Architecture Report

## Executive Summary

**beads_rust** is a local-first issue tracker CLI optimized for AI coding agents. Built with Rust 1.85, Edition 2024.

**Key Statistics:**
- ~3,500 lines of code across 12 modules
- Language: Rust 1.85 (Edition 2024)
- Key dependencies: clap, rusqlite, serde, chrono, anyhow

---

## Entry Points

| Entry | Location | Purpose |
|-------|----------|---------|
| CLI main | `src/main.rs:1` | Parses args via clap, dispatches to commands |
| Commands | `src/commands/*.rs` | Individual command implementations |

---

## Key Types

| Type | Location | Purpose |
|------|----------|---------|
| `Issue` | `src/model.rs:15` | Core domain object - the issue/bead |
| `Storage` | `src/storage.rs:1` | SQLite persistence layer |
| `Cli` | `src/main.rs:20` | clap-derived CLI structure |
| `Config` | `src/config.rs:1` | Runtime configuration |

---

## Data Flow

CLI Input (br create "title") │ ▼ Clap Parser ─── validates args │ ▼ Command Handler ─── orchestrates │ ▼ Storage Layer ─── SQLite + JSONL sync │ ▼ Output (JSON/table/confirmation)

**Happy Path:** User runs `br create "Fix bug"` → clap parses → CreateCommand runs → Storage inserts to SQLite → JSONL sync triggered → ID printed.

---

## External Dependencies

| Dependency | Purpose | Critical? |
|------------|---------|-----------|
| rusqlite (bundled SQLite) | Local persistence | Yes |
| serde/serde_json | Serialization | Yes |
| clap | CLI parsing | Yes |
| chrono | Timestamps | Yes |
| rich_rust | Terminal formatting | No |

---

## Configuration

| Source | Example | Priority |
|--------|---------|----------|
| Env var | `BR_DB_PATH=/path/to/db` | Highest |
| Config file | `.beads/config.yaml` | Medium |
| Default | `.beads/beads.db` | Lowest |

---

## Test Infrastructure

| Type | Location | Count |
|------|----------|-------|
| Unit tests | `src/*.rs` (inline) | ~40 |
| Integration | `tests/` | ~15 |
| Benchmarks | `benches/storage_perf.rs` | 1 suite |

**Running Tests:**

cargo test # All tests cargo test --lib # Unit only cargo bench # Performance benchmarks

---

## Notes & Gotchas

- JSONL sync is one-way (SQLite → JSONL) for git compatibility
- Issue IDs are base36 encoded for compactness
- `--robot` flag outputs JSON for agent consumption

---

Example 2: Web Service (Express/TypeScript)

# api-gateway - Technical Architecture Report

## Executive Summary

**api-gateway** is an Express.js API gateway handling auth, rate limiting, and request routing. Built with TypeScript 5.3.

**Key Statistics:**
- ~2,100 lines across 8 modules
- Language: TypeScript 5.3
- Key dependencies: express, passport, redis, zod, pino

---

## Entry Points

| Entry | Location | Purpose |
|-------|----------|---------|
| Server boot | `src/index.ts:1` | Express app initialization |
| Router setup | `src/routes/index.ts:1` | Route registration |
| Middleware chain | `src/middleware/index.ts:1` | Auth, rate limit, logging |

---

## Key Types

| Type | Location | Purpose |
|------|----------|---------|
| `User` | `src/types/user.ts:5` | Authenticated user shape |
| `ApiRequest` | `src/types/request.ts:1` | Extended Express Request |
| `RateLimitConfig` | `src/config/limits.ts:10` | Per-route rate limits |

---

## Data Flow

HTTP Request │ ▼ Express Router ─── path matching │ ▼ Middleware Stack ─── auth, rate limit, validation │ ▼ Route Handler ─── business logic │ ▼ Upstream Service ─── proxy to microservices │ ▼ Response Transform ─── standardize format │ ▼ HTTP Response

---

## External Dependencies

| Dependency | Purpose | Critical? |
|------------|---------|-----------|
| Redis | Rate limiting, sessions | Yes |
| PostgreSQL | User data | Yes |
| Upstream APIs | Backend services | Yes |
| Sentry | Error tracking | No |

---

## Configuration

| Source | Example | Priority |
|--------|---------|----------|
| Env var | `DATABASE_URL`, `REDIS_URL` | Highest |
| Config file | `config/production.json` | Medium |
| Default | `config/default.json` | Lowest |

Uses `node-config` for layered configuration.

---

Quick vs Deep Reports

Quick Scan Prompt

Give me a quick architecture overview of this codebase:
- What is it?
- Entry points (main, routes, handlers)
- 3 key types
- Main data flow

Keep it under 200 lines.

Deep Dive Additions

For deep reports, also include:

• Sequence diagrams for critical flows
• All error handling paths
• Performance characteristics
• Security considerations
• Technical debt inventory

Comprehensive Technical Architecture Report Template

Copy this template and fill in the sections.

---

[Project Name] - Technical Architecture Report

Executive Summary

[Project] is a [CLI tool / web service / library] that [main purpose]. Built with [language] [version].

Key Statistics:

• ~X,XXX lines of code across Y modules
• Language: [Rust 1.XX / TypeScript 5.X / Python 3.XX]
• Key dependencies: [dep1], [dep2], [dep3], [dep4], [dep5]

---

Entry Points

---

Key Types

---

Data Flow

[Input Source]
     │
     ▼
[Entry Point] ─── parses/validates
     │
     ▼
[Handler/Controller] ─── orchestrates
     │
     ▼
[Core Domain Logic] ─── business rules
     │
     ▼
[Storage/External] ─── persists/calls
     │
     ▼
[Output/Response]

Happy Path Description: 1. User invokes [command/endpoint] 2. [Entry] parses input and creates [Type] 3. [Handler] calls [Core] which processes... 4. Result is [stored/returned/displayed]

---

External Dependencies

---

Configuration

Key Config Options:

• option_name: Description, default value
• another_option: Description, default value

---

Module Structure

src/
├── main.rs          # Entry point, CLI setup
├── config.rs        # Configuration loading
├── model/           # Core domain types
│   ├── mod.rs
│   └── types.rs
├── handlers/        # Request/command handlers
│   └── mod.rs
├── storage/         # Persistence layer
│   ├── mod.rs
│   └── sqlite.rs
└── utils/           # Shared utilities
    └── mod.rs

---

Test Infrastructure

Running Tests:

cargo test              # All tests
cargo test --lib        # Unit only
cargo test --test e2e   # E2E only

---

Error Handling

• Error type: src/error.rs - uses thiserror/anyhow
• Propagation: ? operator, Result<T, Error>
• User-facing: Formatted messages in CLI/API responses

---

Logging

• Framework: tracing / log / env_logger
• Levels: Configurable via RUST_LOG or --verbose
• Output: stderr (CLI), structured JSON (service)

---

Notes & Gotchas

• [Any non-obvious behavior]
• [Known limitations]
• [Areas needing improvement]

---

Generated: [Date] By: [Agent/Human]

THE EXACT PROMPT — Quick Version

Review this text and remove any AI slop patterns: excessive emdashes, "Here's why"
constructions, "It's not X, it's Y" formulas, and other LLM writing tells. Recast
sentences to sound more naturally human. Use ultrathink.

---

Patterns to Eliminate

---

Emdash Alternatives

Sometimes the best fix is to split into two sentences.

---

Before/After Examples

Emdash Overuse

Before:

This tool—which we built from scratch—handles everything automatically—from parsing to output.

After:

This tool handles everything automatically, from parsing to output. We built it from scratch.

"Here's why" Pattern

Before:

We chose Rust for this component. Here's why: performance matters.

After:

We chose Rust for this component because performance matters.

Contrast Formula

Before:

It's not just a linter—it's a complete code quality system.

After:

This complete code quality system goes beyond basic linting.

Forced Enthusiasm

Before:

# Getting Started

Let's dive in! We're excited to help you get up and running.

After:

# Getting Started

Install the tool and run your first command in under a minute.

---

Why Manual Review is Required

1. Context matters — Sometimes an emdash is actually the right choice 2. Recasting sentences — Often the fix isn't substitution but rewriting 3. Tone consistency — Need to maintain voice throughout 4. Judgment calls — Some patterns are fine in moderation

---

When to De-Slopify

• Before publishing a README
• Before releasing documentation
• After AI-assisted writing sessions
• During documentation reviews

---

What NOT to Fix

• Technical accuracy — Don't sacrifice correctness for style
• Necessary structure — Headers, lists are fine
• Clear explanations — Being thorough isn't slop
• Code examples — Focus on prose, not code

---

References

Documentation Generation Templates

CODING: Code-Map Template

CRITICAL: Load code-map-standard skill before generating.

---
title: "[Feature Name]"
sources: [path/to/main.py]
last_updated: YYYY-MM-DD
---

# [Feature Name]

## Current Status

[One-liner with date]

## Overview

[2-3 sentences]

## State Machine

[ASCII diagram if applicable]

## Inputs/Outputs

| Type | Name | Description |
|------|------|-------------|

## Data Flow

[ASCII diagram]

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|

## Code Signposts

| Component | Location | Purpose |
|-----------|----------|---------|

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|

## Prometheus Metrics

| Metric | Type | Labels | PromQL Example |
|--------|------|--------|----------------|

## Error Handling

| Error | Cause | Resolution |
|-------|-------|------------|

## Unit Tests

| Test File | Coverage |
|-----------|----------|

## Integration Tests

| Test | What It Validates |
|------|-------------------|

## Example Usage

### curl
### SDK

## Related Features

## Known Limitations

## Learnings

### What Worked
### What We'd Change

---

INFORMATIONAL: Corpus Section Template

---
title: "Document Title"
summary: "One-line summary for search"
tags: [tag1, tag2]
tokens: 1500
last_updated: YYYY-MM-DD
---

# Title

## Overview

[Introduction paragraph]

## Key Concepts

### Concept 1
### Concept 2

## Practical Application

## Related Topics

- [Link 1](../path/to/doc.md)
- [Link 2](../path/to/doc.md)

## References

- External sources

---

OPS: Helm Chart Template

# [Chart Name]

## Overview

[Description from Chart.yaml]

## Quick Start

helm install [release] ./charts/[name]

## Values Reference

| Key | Type | Default | Description |
|-----|------|---------|-------------|

## Dependencies

| Chart | Version | Condition |
|-------|---------|-----------|

## Common Overrides

### Development
### Staging
### Production

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|

---

Stub Template (--create mode)

For undocumented features:

---
title: "[Feature Name]"
status: STUB
created: YYYY-MM-DD
sources: [detected source files]
---

# [Feature Name]

> AUTO-GENERATED STUB - Replace with actual content

## Current Status

[Discovered but not documented]

## Overview

[Brief description of this feature]

## Sources

- `path/to/source.py`

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|

---

Section Markers

Use markers to control auto-generation behavior:

<!-- HUMAN-MAINTAINED: Do not auto-generate -->
[This section is preserved during updates]

<!-- AUTO-GENERATED: Safe to replace -->
[This section is regenerated from source]

Merge Strategy: 1. HUMAN-MAINTAINED sections: Always preserve 2. AUTO-GENERATED sections: Replace with fresh data 3. Frontmatter: Merge (add missing, update tokens/dates)

Documentation Patterns from Beads

Extracted from analysis of beads (chronicle) repository.

Beads demonstrates exemplary OSS documentation practices.

Overview

Beads is a Git-backed issue tracker for AI-supervised coding workflows. As of v0.48.0, it has ~90 markdown files with comprehensive documentation.

Why study beads?

• Actively maintained OSS project
• Targets AI-assisted development (similar audience)
• Extensive documentation coverage
• Clear writing style

---

README.md Pattern

Structure

1. Project name + one-liner
2. Quick install (single command)
3. Quick start (3-5 commands)
4. Key features (bullet list)
5. Documentation links
6. Community/contributing
7. License

Key Elements

Title + Tagline:

# beads (bd)

> Git-backed issue tracker for AI-supervised coding workflows.

Quick Install:

## Installation

brew tap steveyegge/beads && brew install bd

Quick Start:

## Quick Start

bd init # Initialize in project bd create "Fix bug" -p 1 # Create issue bd ready # Find unblocked work bd vc status # Optional Dolt status check; JSONL auto-sync is automatic

Features as Bullets (not walls of text):

## Features

- **Zero setup** - `bd init` creates project-local database
- **Dependency tracking** - Four dependency types
- **Ready work detection** - Find issues with no blockers
- **Agent-friendly** - `--json` flags for programmatic use

---

AGENTS.md Pattern

Structure

1. Quick reference commands
2. Session close protocol
3. Workflow overview
4. Common operations

Key Elements

Command Quick Reference:

## Quick Reference

bd ready # Find available work bd show <id> # View issue details bd update <id> --status in_progress # Claim work bd close <id> # Complete work bd vc status # Inspect Dolt state if needed (JSONL auto-sync is automatic)

Session Close Protocol (Critical):

## Landing the Plane (Session Completion)

**When ending a work session**, you MUST complete ALL steps below.
Work is NOT complete until `git push` succeeds.

**MANDATORY WORKFLOW:**

1. **File issues for remaining work**
2. **Run quality gates** (if code changed)
3. **Update issue status**
4. **PUSH TO REMOTE** - This is MANDATORY
5. **Verify** - All changes committed AND pushed

Emphasis on Critical Rules:

**CRITICAL RULES:**
- Work is NOT complete until `git push` succeeds
- NEVER stop before pushing
- NEVER say "ready to push when you are" - YOU must push

---

CLI_REFERENCE.md Pattern

Structure

1. Overview table of all commands
2. Global flags section
3. Each command with:
   - Synopsis
   - Description
   - Flags table
   - Examples

Key Elements

Command Synopsis:

## bd create

Create a new issue.

### Synopsis

bd create <title> [flags]

### Flags

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--type` | `-t` | `task` | Issue type |
| `--priority` | `-p` | `2` | Priority (0-4) |
| `--description` | `-d` | | Issue description |
| `--json` | | `false` | Output as JSON |

### Examples

Create a bug with high priority

bd create "Login fails on Safari" -t bug -p 1

Create with description

bd create "Add dark mode" -d "Support system preference"

---

TROUBLESHOOTING.md Pattern

Structure

1. Quick fixes section (most common issues)
2. Categorized issues
3. Each issue with:
   - Symptoms
   - Cause
   - Solution
4. Recovery procedures

Key Elements

Issue Format:

### Issue: Database is locked

**Symptoms:**

bd: database is locked (SQLITE_BUSY)

**Cause:** Another process has the database open.

**Solutions:**

1. **Stop daemon and retry:**

bd daemon stop bd <your-command>

2. **Check for hung processes:**

ps aux | grep bd kill <pid>

Quick Fixes Section:

## Quick Fixes

| Problem | Solution |
|---------|----------|
| "database is locked" | `bd daemon stop && bd daemon start` |
| "JSONL conflict markers" | `git checkout --theirs .beads/issues.jsonl` |
| "circular dependency" | `bd doctor` (diagnose only) |

---

CONFIG.md Pattern

Structure

1. Configuration overview
2. Configuration levels (project, user, env)
3. Settings table with all options
4. Examples for common scenarios

Key Elements

Configuration Levels:

## Configuration Precedence

1. **Environment variables** (highest) - `BEADS_*`
2. **CLI flags** - `--flag`
3. **Project config** - `.beads/config.yaml`
4. **User config** - `~/.config/beads/config.yaml`
5. **Defaults** (lowest)

Settings Table:

## Settings Reference

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `sync.auto_commit` | bool | `true` | Auto-commit on sync |
| `sync.auto_push` | bool | `false` | Auto-push on sync |
| `sync.branch` | string | | Separate sync branch |
| `daemon.port` | int | `0` | Daemon port (0=auto) |

---

CHANGELOG.md Pattern

Format

Based on Keep a Changelog:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.48.0] - 2026-01-17

### Added
- **VersionedStorage interface** - Abstract storage layer
- **`bd types` command** - List valid issue types (#1102)

### Fixed
- **Doctor sync branch health check** - Removed destructive --fix (GH#1062)
- **Duplicate merge target selection** - Use combined weight (GH#1022)

### Changed
- **Daemon CLI refactor** - Consolidated subcommands

### Documentation
- Add lazybeads TUI to community tools (#951)

Key Practices

1. Link issue numbers - (#123) or (GH#123) 2. Bold feature names - **Feature name** 3. Categorize changes - Added, Fixed, Changed, etc. 4. Include dates - [0.48.0] - 2026-01-17 5. Link comparison URLs at bottom

---

Documentation Organization

Directory Structure

beads/
├── README.md                 # Overview + quick start
├── AGENTS.md                 # AI assistant guide
├── CONTRIBUTING.md           # Contributor guide
├── CHANGELOG.md              # Version history
├── SECURITY.md               # Vulnerability reporting
│
├── docs/
│   ├── QUICKSTART.md         # Detailed getting started
│   ├── CLI_REFERENCE.md      # Complete command reference
│   ├── ARCHITECTURE.md       # System design
│   ├── CONFIG.md             # Configuration options
│   ├── TROUBLESHOOTING.md    # Common issues
│   ├── FAQ.md                # Frequently asked questions
│   ├── GIT_INTEGRATION.md    # Git workflows
│   ├── WORKTREES.md          # Git worktree support
│   ├── MULTI_REPO_*.md       # Multi-repo patterns
│   └── <FEATURE>.md          # Feature-specific docs
│
├── examples/
│   ├── README.md             # Examples index
│   ├── python-agent/         # Python integration
│   ├── bash-agent/           # Shell scripts
│   └── <pattern>/            # Usage patterns
│
└── integrations/
    ├── beads-mcp/            # MCP server
    └── claude-code/          # Claude Code plugin

Navigation Principles

1. README links to docs/ - Don't duplicate, link 2. Each doc is self-contained - Can be read standalone 3. Cross-references - "See also" sections 4. Index pages - examples/README.md lists all examples

---

Style Guidelines

From Beads' Writing Style

1. Direct language - "Run this command" not "You may want to run" 2. Active voice - "The daemon exports" not "Issues are exported by" 3. Tables for structured data - Commands, flags, options 4. Code blocks for examples - Always with language hint 5. Warnings are prominent - Use blockquotes or boxes 6. No jargon without definition - Explain terms on first use

Warning Format

**⚠️ WARNING:** Daemon mode does NOT work correctly with git worktrees.

Or:

> **Note:** For environments with shell access, CLI is recommended over MCP.

Example Quality

Bad:

Run the create command to create an issue.

Good:

bd create "Fix authentication bug" -t bug -p 1 --json

---

Metrics from Beads

Coverage Analysis

• Tier 1: 4/4 (LICENSE, README, CONTRIBUTING, CODE_OF_CONDUCT)
• Tier 2: 5/5 (SECURITY, CHANGELOG, AGENTS, templates)
• Tier 3: 6+/6 (QUICKSTART, ARCHITECTURE, CLI_REFERENCE, CONFIG, TROUBLESHOOTING, examples)

Score: 100% coverage across all tiers

---

Applying to Your Project

1. Start with README.md - Use beads' structure as template 2. Add AGENTS.md early - AI assistants need context 3. Document commands - CLI_REFERENCE.md for any CLI 4. Anticipate problems - TROUBLESHOOTING.md saves support time 5. Keep CHANGELOG - Start from v0.1.0, update every release

Documentation Tiers

Prioritized documentation requirements for OSS projects.

Based on analysis of successful open source projects.

Overview

Not all documentation is created equal. This tiered approach ensures critical files are prioritized while allowing progressive enhancement.

---

Tier 1: Required (Legal + Essential)

Must have for any public repository.

Why These Are Required

• LICENSE: Without a license, code is "all rights reserved" by default
• README.md: First file GitHub displays, defines project identity
• CONTRIBUTING.md: Reduces friction for new contributors
• CODE_OF_CONDUCT.md: Sets expectations, required by many organizations

Audit Check

TIER1_SCORE=0
[[ -f LICENSE ]] && ((TIER1_SCORE++))
[[ -f README.md ]] && ((TIER1_SCORE++))
[[ -f CONTRIBUTING.md ]] && ((TIER1_SCORE++))
[[ -f CODE_OF_CONDUCT.md ]] && ((TIER1_SCORE++))
echo "Tier 1: $TIER1_SCORE/4"

---

Tier 2: Standard (Professional Quality)

Expected for production-quality projects.

Why These Matter

• SECURITY.md: Private vulnerability disclosure channel
• CHANGELOG.md: Users need to know what changed between versions
• AGENTS.md: AI assistants (Claude, Copilot) work better with context
• Issue Templates: Reduce noise, get structured reports
• PR Template: Ensure consistency, remind of checklist items

Audit Check

TIER2_SCORE=0
[[ -f SECURITY.md ]] && ((TIER2_SCORE++))
[[ -f CHANGELOG.md ]] && ((TIER2_SCORE++))
[[ -f AGENTS.md ]] && ((TIER2_SCORE++))
[[ -d .github/ISSUE_TEMPLATE ]] && ((TIER2_SCORE++))
[[ -f .github/PULL_REQUEST_TEMPLATE.md ]] && ((TIER2_SCORE++))
echo "Tier 2: $TIER2_SCORE/5"

---

Tier 3: Enhanced (Comprehensive)

For mature projects with complex functionality.

Recommendation Matrix

Audit Check

TIER3_SCORE=0
[[ -f docs/QUICKSTART.md ]] && ((TIER3_SCORE++))
[[ -f docs/ARCHITECTURE.md ]] && ((TIER3_SCORE++))
[[ -f docs/CLI_REFERENCE.md ]] && ((TIER3_SCORE++))
[[ -f docs/CONFIG.md ]] && ((TIER3_SCORE++))
[[ -f docs/TROUBLESHOOTING.md ]] && ((TIER3_SCORE++))
[[ -d examples ]] && ((TIER3_SCORE++))
echo "Tier 3: $TIER3_SCORE/6"

---

Tier 4: Specialized

Domain-specific documentation.

---

Scoring Guide

---

Progressive Enhancement Strategy

Phase 1: Go Public (Tier 1)

Before making a repo public: 1. Add LICENSE (choose appropriate license) 2. Write README.md with basic info 3. Add CONTRIBUTING.md (fork/PR workflow) 4. Add CODE_OF_CONDUCT.md (Contributor Covenant)

Phase 2: Attract Contributors (Tier 2)

After initial public release: 1. Add SECURITY.md for vulnerability reports 2. Start CHANGELOG.md for version tracking 3. Add issue/PR templates 4. Create AGENTS.md for AI assistants

Phase 3: Scale (Tier 3)

As project grows: 1. Split README content into docs/ 2. Add troubleshooting for common issues 3. Document architecture for contributors 4. Create comprehensive examples

---

Examples from Beads

Beads (chronicle) demonstrates excellent documentation coverage:

Tier 1 (all present):

• LICENSE (MIT)
• README.md (comprehensive overview)
• CONTRIBUTING.md (detailed guide)
• CODE_OF_CONDUCT.md (Contributor Covenant)

Tier 2 (all present):

• SECURITY.md (vulnerability reporting)
• CHANGELOG.md (Keep a Changelog format)
• AGENTS.md (AI workflow guide)
• Issue templates (bug report, feature request)
• PR template

Tier 3 (extensive):

• docs/QUICKSTART.md
• docs/ARCHITECTURE.md
• docs/CLI_REFERENCE.md (~800 lines)
• docs/CONFIG.md (~615 lines)
• docs/TROUBLESHOOTING.md (~845 lines)
• docs/FAQ.md
• docs/GIT_INTEGRATION.md
• docs/WORKTREES.md
• examples/ directory with multiple patterns

Key Patterns:

• Clear separation between user docs and developer docs
• Extensive troubleshooting documentation
• Multiple integration guides (MCP, Claude Code, etc.)
• Active CHANGELOG with detailed version notes

OSS Doc Pack — scaffold/audit open-source documentation (/doc --mode=oss)

Scaffold and audit the standard documentation pack for an open-source release. This is the full contract behind /doc --mode=oss; it absorbed the former /oss-docs skill. Output contract: CONTRIBUTING.md, CHANGELOG.md, AGENTS.md, and the rest of the OSS doc tiers.

Overview

This mode helps prepare repositories for open source release by: 1. Auditing existing documentation completeness 2. Scaffolding missing standard files 3. Generating content tailored to project type

(The legacy /oss-docs audit, /oss-docs scaffold, /oss-docs validate triggers route here.)

Commands

---

Phase 0: Project Detection

# Determine project type and language
PROJECT_NAME=$(basename $(pwd))
LANGUAGES=()

[[ -f go.mod ]] && LANGUAGES+=("go")
[[ -f pyproject.toml ]] || [[ -f setup.py ]] && LANGUAGES+=("python")
[[ -f package.json ]] && LANGUAGES+=("javascript")
[[ -f Cargo.toml ]] && LANGUAGES+=("rust")

# Detect project category
if [[ -f Dockerfile ]] && [[ -d cmd ]]; then
    PROJECT_TYPE="cli"
elif [[ -d config/crd ]]; then
    PROJECT_TYPE="operator"
elif [[ -f Chart.yaml ]]; then
    PROJECT_TYPE="helm"
else
    PROJECT_TYPE="library"
fi

---

Subcommand: audit

Required Files (Tier 1 - Core)

Recommended Files (Tier 2 - Standard)

Optional Files (Tier 3 - Enhanced)

Full tier definitions: oss-documentation-tiers.md.

---

Subcommand: scaffold

Template Selection

Per-type content templates: oss-project-types.md.

For a machine-readable tiered audit (project type + per-tier scores + totals as JSON), run the helper script: bash skills/doc/scripts/audit-oss-docs.sh --json.

---

Documentation Organization

project/
├── README.md              # Overview + quick start
├── AGENTS.md              # AI assistant context
├── CONTRIBUTING.md        # Contributor guide
├── CHANGELOG.md           # Keep a Changelog format
├── docs/
│   ├── QUICKSTART.md      # Detailed getting started
│   ├── CLI_REFERENCE.md   # Complete command reference
│   ├── ARCHITECTURE.md    # System design
│   └── CONFIG.md          # Configuration options
└── examples/
    └── README.md          # Examples index

---

AGENTS.md Pattern

# Agent Instructions

This project uses **<tool>** for <purpose>. Run `<onboard-cmd>` to get started.

## Quick Reference

<cmd1> # Do thing 1 <cmd2> # Do thing 2

## Landing the Plane (Session Completion)

**MANDATORY WORKFLOW:**

1. **Run quality gates** - Tests, linters, builds
2. **Commit changes** - Meaningful commit message
3. **PUSH TO REMOTE** - This is MANDATORY
4. **Verify** - All changes committed AND pushed

Beads-tracker AGENTS.md patterns: oss-beads-patterns.md.

---

Style Guidelines

1. Be direct - Get to the point quickly 2. Be friendly - Welcome contributions 3. Be concise - Avoid boilerplate 4. Use tables - For commands, options, features 5. Show examples - Code blocks over prose 6. Link liberally - Cross-reference related docs

---

Mode Boundaries

DO:

• Audit existing documentation
• Generate standard OSS files
• Validate documentation quality

DON'T:

• Overwrite existing content without confirmation
• Generate code documentation (use /doc gen — the default doc mode)
• Generate the README hero/landing page (use /doc --mode=readme)
• Create CI/CD files (out of scope — configure CI/CD separately)

---

Troubleshooting

Project Types Reference

Documentation patterns by project category.

Templates adapt to project type for relevant content.

Type Detection

#!/bin/bash
# Detect project type based on file patterns

detect_project_type() {
    local type="unknown"
    local confidence=0

    # CLI Tool (Go)
    if [[ -f go.mod ]] && [[ -d cmd ]]; then
        type="cli-go"
        confidence=90

    # CLI Tool (Python)
    elif [[ -f pyproject.toml ]] && grep -q "scripts" pyproject.toml 2>/dev/null; then
        type="cli-python"
        confidence=85

    # Kubernetes Operator
    elif [[ -f PROJECT ]] || [[ -d config/crd ]] || [[ -f Makefile ]] && grep -q "controller-gen" Makefile 2>/dev/null; then
        type="operator"
        confidence=95

    # Helm Chart
    elif [[ -f Chart.yaml ]]; then
        type="helm"
        confidence=100

    # Go Library
    elif [[ -f go.mod ]] && [[ ! -d cmd ]]; then
        type="library-go"
        confidence=80

    # Python Library
    elif [[ -f pyproject.toml ]] || [[ -f setup.py ]]; then
        type="library-python"
        confidence=75

    # Node.js
    elif [[ -f package.json ]]; then
        if grep -q '"bin"' package.json 2>/dev/null; then
            type="cli-node"
            confidence=85
        else
            type="library-node"
            confidence=75
        fi

    # Rust
    elif [[ -f Cargo.toml ]]; then
        if [[ -d src/bin ]] || grep -q '^\[\[bin\]\]' Cargo.toml 2>/dev/null; then
            type="cli-rust"
            confidence=85
        else
            type="library-rust"
            confidence=80
        fi

    # Documentation/Informational
    elif [[ -d docs ]] && [[ $(find . -maxdepth 1 -name "*.md" | wc -l) -gt 5 ]]; then
        type="docs"
        confidence=70
    fi

    echo "$type:$confidence"
}

---

Type: cli-go

Go CLI tools (like beads, gastown)

Detection Signals

• go.mod present
• cmd/ directory with main packages
• Often has internal/ for private packages

Recommended Documentation

README Template Key Sections

## Installation

Homebrew (recommended)

brew install <name>

Go install

go install <module>/cmd/<name>@latest

From source

git clone <repo> cd <repo> go build -o <name> ./cmd/<name>

## Quick Start

<name> init <name> <primary-command>

## Commands

| Command | Description |
|---------|-------------|
| `init` | Initialize configuration |
| `<cmd>` | Primary operation |
| `help` | Show help |

---

Type: operator

Kubernetes Operators (kubebuilder, operator-sdk)

Detection Signals

• PROJECT file (kubebuilder marker)
• config/crd/ directory
• Makefile with controller-gen references
• api/ or apis/ directory with types

Recommended Documentation

README Template Key Sections

## Installation

kubectl apply -f https://github.com/<owner>/<repo>/releases/latest/download/install.yaml

Or with Helm:

helm install <name> <repo>/<chart>

## CRDs

| Kind | API Version | Description |
|------|-------------|-------------|
| `<Kind>` | `<group>/<version>` | Manages... |

## Quick Start

apiVersion: <group>/<version> kind: <Kind> metadata: name: example spec:

minimal spec

## RBAC Requirements

The operator requires the following permissions:
- `<resource>`: create, get, list, watch, update, delete

SECURITY.md Focus

## Security Considerations

- **Pod Security:** Runs with restricted security context
- **RBAC:** Minimal permissions following least-privilege
- **Secrets:** Never logged, stored encrypted at rest
- **Network:** Egress to API server only

---

Type: helm

Helm Charts

Detection Signals

• Chart.yaml present
• values.yaml present
• templates/ directory

Recommended Documentation

README Template Key Sections

## Installation

helm repo add <repo> <url> helm install <release> <repo>/<chart>

## Configuration

| Parameter | Description | Default |
|-----------|-------------|---------|
| `image.repository` | Image name | `<default>` |
| `image.tag` | Image tag | `latest` |
| `replicas` | Pod replicas | `1` |

See `values.yaml` for all options.

## Upgrading

helm upgrade <release> <repo>/<chart>

---

Type: library-go

Go Libraries

Detection Signals

• go.mod present
• No cmd/ directory
• Public package exports

Recommended Documentation

README Template Key Sections

## Installation

go get <module>

## Usage

import "<module>"

func main() { client := pkg.New() result, err := client.DoSomething() }

## API

See [pkg.go.dev](https://pkg.go.dev/<module>) for complete API documentation.

---

Type: library-python

Python Libraries

Detection Signals

• pyproject.toml or setup.py
• src/ or package directory
• No CLI entry points

Recommended Documentation

README Template Key Sections

## Installation

pip install <package>

or

uv pip install <package>

## Usage

from <package> import Client

client = Client() result = client.do_something()

## API Documentation

See your hosted API documentation URL for complete API reference.

---

Type: cli-python

Python CLI Tools

Detection Signals

• pyproject.toml with [project.scripts]
• Click, Typer, or argparse usage
• Entry point defined

Recommended Documentation

Similar to cli-go but with Python installation methods:

## Installation

pip

pip install <package>

pipx (recommended for CLI tools)

pipx install <package>

uv

uv tool install <package>

---

Type: docs

Documentation-Only Repositories

Detection Signals

• Heavy markdown content
• docs/ directory dominant
• Minimal code

Recommended Documentation

---

Language Detection

#!/bin/bash
# Detect languages in project

detect_languages() {
    local langs=()

    [[ -f go.mod ]] && langs+=("go")
    [[ -f pyproject.toml ]] || [[ -f setup.py ]] && langs+=("python")
    [[ -f package.json ]] && langs+=("javascript")
    [[ -f Cargo.toml ]] && langs+=("rust")
    [[ -f Makefile ]] && langs+=("make")
    [[ $(find . -name "*.sh" -maxdepth 2 | wc -l) -gt 0 ]] && langs+=("shell")
    [[ -f Dockerfile ]] && langs+=("docker")
    [[ -f Chart.yaml ]] && langs+=("helm")

    echo "${langs[*]}"
}

---

Command Extraction

For CLI tools, extract commands for documentation:

Go (cobra)

# Find cobra commands
grep -r "func.*Command\(\)" cmd/ --include="*.go" | \
    sed 's/.*func \(.*\)Command.*/\1/'

Python (click/typer)

# Find click commands
grep -r "@click.command\|@app.command" --include="*.py" | \
    sed 's/.*def \([a-z_]*\).*/\1/'

---

Test Command Detection

detect_test_command() {
    if [[ -f go.mod ]]; then
        echo "go test ./..."
    elif [[ -f pyproject.toml ]]; then
        if grep -q "pytest" pyproject.toml; then
            echo "pytest"
        else
            echo "python -m pytest"
        fi
    elif [[ -f package.json ]]; then
        echo "npm test"
    elif [[ -f Cargo.toml ]]; then
        echo "cargo test"
    elif [[ -f Makefile ]] && grep -q "^test:" Makefile; then
        echo "make test"
    else
        echo "<TEST_COMMAND>"
    fi
}

Project Type Detection

Score-based classification into CODING, INFORMATIONAL, or OPS.

CODING Signals

Threshold: Score >= 5 = Likely CODING repo

---

INFORMATIONAL Signals

Threshold: Score >= 5 = Likely INFORMATIONAL repo

---

OPS Signals

Threshold: Score >= 5 = Likely OPS repo

---

Tie-Breaking

When scores are equal: CODING > OPS > INFORMATIONAL

Rationale: Code repos need more precise docs, ops is next most critical.

---

Type-Specific Behaviors

Prose And Report Workmanship

Use this reference when documentation needs to read like maintainable project material rather than agent-generated filler.

Prose Cleanup

Remove writing artifacts that do not help the operator:

• Inflated claims without evidence.
• Repeated "not only/but also" constructions.
• Decorative punctuation or emphasis that hides the main point.
• Meta-commentary about how the document is written.
• Long setup before the command, decision, or finding.

Keep the tone direct, concrete, and source-grounded.

Architecture Report Rules

For codebase reports:

1. Start from the user-facing or operator-facing entry points. 2. Explain the dominant flow before listing files. 3. Name invariants and contracts, not just modules. 4. Separate facts from inferences. 5. End with risks and questions that affect future work.

Final Pass

Before publishing docs:

---

Source: Adapted from an external skill corpus / de-slopify and codebase-report. Pattern-only, no verbatim text.

README Craft — Gold-Standard README Generation (/doc --mode=readme)

Generate a README that converts skimmers into users and satisfies deep readers — then validate it with a council. This is the full contract behind /doc --mode=readme; it absorbed the former /readme skill.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Quick Start

/doc --mode=readme                    # Interview + generate + validate (new README)
/doc --mode=readme --rewrite          # Rewrite existing README with same patterns
/doc --mode=readme --validate         # Council-validate an existing README without rewriting

(The legacy /readme, /readme --rewrite, /readme --validate triggers route here.)

---

The Patterns

These are non-negotiable. Every README this mode produces follows them.

1. Lead with the problem, not the framework

Bad: "A DevOps layer implementing the Three Ways for agent workflows." Good: "Coding agents forget everything between sessions. This fixes that."

The reader should understand what pain you solve in one sentence. No jargon, no framework names, no theory. The problem is the hook. (Note: framework references like Three Ways and Meadows belong in the body as design rationale — just don't lead with them.)

2. Acknowledge prior art

If your approach resembles established practices (agile, SCRUM, spec-driven development, CI/CD), say so explicitly:

"If you've done X, you already know the fix. What's new is Y."

This disarms experienced practitioners who would otherwise dismiss you as reinventing the wheel. Claim only what's genuinely novel.

3. Show, don't claim

Bad: "This is what makes X different. The system compounds." Good: A terminal transcript showing the system working.

Assertions without evidence trigger hostility. Concrete examples > adjectives. If you can't show it in a code block, it's not ready for the README.

4. State your differentiator once

One clear explanation. One demonstration. That's the max. Repeating your core value proposition in every section crosses from reinforcement into marketing copy. Trust the reader to absorb it the first time.

5. Trust block near install

Before a user installs anything that runs code, hooks, or modifies config, they need to see:

This goes near the install command, not buried in an FAQ.

6. Collapse depth, don't delete it

Detailed workflow steps, architecture deep-dives, theory, and reference material belong in <details> blocks. Skimmers get the fast path. Deep readers click to expand. Never delete depth to achieve brevity — collapse it.

7. Strip guru tone

No "What N months taught me." No "I come from X, so I applied Y." No "This is what makes us different." Let the tool speak for itself. Humility disarms. Condescension repels.

8. Section order serves adoption

Problem → Install → See It Work → Getting Started Path → How It Works (collapsed) → Reference

Theory and architecture come AFTER the user has seen examples and knows how to start. Never put "why this is important" before "how to try it."

---

Execution Steps

Given /doc --mode=readme [--rewrite] [--validate]:

Step 1: Pre-flight

ls README.md 2>/dev/null

Mode detection:

• --validate + README exists → skip to Step 5 (council validation only)
• --rewrite + README exists → read existing, use as context for rewrite
• README exists, no flags → ask:
• "Rewrite — regenerate with gold-standard patterns"
• "Validate — council-check the existing README"
• "Cancel"
• No README exists → proceed to Step 2 (generate from scratch)

Step 2: Gather Context

Read available project files silently (no output to user):

ls README.md PRODUCT.md package.json pyproject.toml go.mod Cargo.toml Makefile 2>/dev/null
ls -d src/ lib/ cmd/ app/ 2>/dev/null
ls -d docs/ 2>/dev/null
ls LICENSE CHANGELOG.md 2>/dev/null

Extract:

• Project name from manifest files
• Language/runtime from build files
• Existing description from README or PRODUCT.md
• License from LICENSE file
• Install method from manifest (npm, pip, brew, go install, cargo, etc.)

Step 3: Interview

Use AskUserQuestion for each section. Pre-populate suggestions from Step 2 where possible. Keep questions short.

3a: The Problem

Ask: "What problem does this solve? One sentence — what pain does your user have?"

Options (derived from existing README/PRODUCT.md if available):

• Suggested problem statement
• A punchier variant
• "Let me type my own"

3b: The Fix

Ask: "How does it fix that problem? One sentence — what does your tool actually do?"

3c: Who Is It For

Ask: "Who is this for? Name the runtime, framework, or role."

Example: "Python developers using FastAPI" or "Anyone running Claude Code or Cursor"

3d: Install

Ask: "What's the install command? (We'll put this front and center)"

Options:

• Detected from manifest (e.g., npm install <pkg>, pip install <pkg>)
• "Let me type my own"

3e: Quick Demo

Ask: "What's the simplest thing a user can do after installing to see it work? (A command, a code snippet, or a terminal session)"

3f: Trust Concerns

Ask: "Does your tool do any of these? Check all that apply."

• Runs shell commands or hooks
• Modifies config files outside the project
• Makes network calls
• Creates files in the user's repo
• None of the above

3g: Prior Art (optional)

Ask: "Are there similar tools? If so, how is yours different? (Be honest — readers who know the space will check)"

Options:

• "Yes, let me describe" → follow up
• "Not really / I'll skip this"

Step 4: Generate README

Using the interview responses and the 8 patterns above, generate the README with this structure:

<div align="center">

# {Project Name}

### {Problem statement — one line}

{Badges}

{Nav links}

</div>

---

> [!IMPORTANT]
> {Trust block — local-only, what it touches, how to disable, how to uninstall}
> (Skip if no trust concerns from 3f)

{Install command}

---

## The Problem

{2-3 sentences expanding the problem. Acknowledge prior art if applicable.
State what's genuinely new about your approach — once.}

---

## See It Work

{Terminal transcript or code example from 3e. Show, don't describe.}

---

## Install

{Full install details, alternative methods in <details> blocks.
"What it touches" table if trust concerns exist.}

---

## Getting Started

{Adoption path — Day 1, Week 1, etc. Or just "Run X, then Y."}

---

## How It Works

{One paragraph summary + diagram if applicable.}

<details>
<summary><b>Details</b> — {phases, architecture, etc.}</summary>

{Deep content here}

</details>

---

## {Reference sections as needed}

{Skills, API, CLI, etc. — collapsed where appropriate}

---

## FAQ

{Top 3 questions inline, link to full FAQ if it exists}

---

## Contributing

## License

Generation rules:

• Every <details> block must have a blank line after <summary> (enables markdown rendering)
• Use markdown inside details blocks, not inline HTML (<code>, <a href>, <br>)
• Trailing blank line before </details>
• No emoji unless the user's existing content uses them
• Flywheel/differentiator concept: state ONCE in "The Problem", demonstrate ONCE in "See It Work"
• Never use phrases: "What N months taught me", "This is what makes X different", "I come from X so I applied Y"

Write the generated README to README.md.

Step 5: Council Validation

Run a council to validate the README:

Skill(skill="council", args="--quick validate README.md — is it clear, non-repetitive, and does it serve both skimmers and deep readers?")

If `--rewrite` or generating from scratch: Use --quick (inline, fast).

If `--validate` on existing README: Use default council (2 judges) for thorough review.

Present the council findings to the user. If significant issues found, offer:

• "Fix — apply council recommendations automatically"
• "Show me — display findings, I'll decide"
• "Ship it — good enough"

Step 6: Apply Fixes (if requested)

Apply council-recommended fixes. Re-validate with --quick to confirm.

Step 7: Report

## README Complete

**File:** README.md
**Sections:** {count}
**Patterns applied:** {list which of the 8 patterns were relevant}
**Council verdict:** {PASS/WARN/FAIL}

{If WARN/FAIL: list the top findings and whether they were fixed}

---

Anti-Patterns to Detect

When rewriting or validating, flag these:

---

Troubleshooting

Documentation Validation Rules

Coverage Metrics by Type

---

INFORMATIONAL Validation

Use Python validator for fast, exhaustive checking:

python3 ~/.claude/scripts/doc-validate.py docs/

Checks Performed

1. Broken Links - ALL internal .md links resolved 2. Orphaned Docs - Files not referenced from any index 3. Index Completeness - READMEs reference all subdirectories 4. Hardcoded Paths - Absolute paths like /Users/, /home/

Why Python, Not Bash?

• Bash loops are O(n*m) and timeout on large repos
• Python processes 350+ files in <5 seconds
• Regex extraction is cleaner and more reliable

Output Format

CRITICAL: Broken Links (81)
   file.md:42 -> missing.md (not found)

MEDIUM: Orphaned Documents (13)
   path/to/orphan.md

LOW: Hardcoded Paths (2)
   file.md:156 -> /Users/...

SUMMARY: 96 issues (81 critical, 13 medium, 2 low)

---

CODING Validation

Required Sections (16)

From code-map-standard skill:

1. Current Status (one-liner with date) 2. Overview (2-3 sentences) 3. State Machine (ASCII diagram if applicable) 4. Inputs/Outputs (table) 5. Data Flow (ASCII diagram) 6. API Endpoints (table with curl examples) 7. Code Signposts (NO line numbers) 8. Configuration (table) 9. Prometheus Metrics (table + PromQL examples) 10. Error Handling (table) 11. Unit Tests (table) 12. Integration Tests (separate from unit) 13. Example Usage (curl + SDK) 14. Related Features (cross-links) 15. Known Limitations 16. Learnings (What Worked + What We'd Change)

Signpost Rules

• NO line numbers - Functions/classes only
• References must exist in source files
• Use semantic names: authenticate(), UserService

---

OPS Validation

Required Sections

1. Overview with Chart.yaml description 2. Quick Start with install command 3. Values Reference table 4. Dependencies table 5. Environment overrides (dev/staging/prod) 6. Troubleshooting table

Values.yaml Coverage

Every key in values.yaml should have:

• Description comment or doc reference
• Type specification
• Default value explanation

---

Coverage Report Format

===================================================================
              DOCUMENTATION COVERAGE REPORT
===================================================================
Repository: [REPO_NAME]
Type: [CODING|INFORMATIONAL|OPS]
Generated: [date]

SUMMARY
-------------------------------------------------------------------
Total Features: 25
Documented: 22 (88%)
Missing: 3
Orphaned: 1

MISSING DOCUMENTATION
-------------------------------------------------------------------
| Feature | Priority | Source Files |
|---------|----------|--------------|
| auth-service | P1 | services/auth/*.py |

ORPHANED DOCUMENTATION
-------------------------------------------------------------------
| Document | Last Updated | Action |
|----------|--------------|--------|
| legacy-api.md | 2023-06-15 | Remove |

===================================================================

---

--create-issues Flag

Auto-create tracking issues for gaps:

# Prefer beads
bd create --title "docs: create code-map for $FEATURE" \
          --type task --priority P1

# Fallback to GitHub
gh issue create --title "docs: create code-map for $FEATURE" \
                --label documentation

---

Semantic Validation (CODING repos)

Structure vs Semantic: Structural validation checks formatting. Semantic validation checks if claims are TRUE.

Semantic Metrics

Ground Truth Pattern

Establish ONE authoritative file per domain. Other docs MUST reference, not duplicate.

Status Validation

Valid status formats:

## Current Status: ✅ RUNNING
Validated: 2026-01-04 against ocppoc cluster

## Current Status: ❌ FAILED
Status: Accepted=False (CRD exists but not running)
Validated: 2026-01-04 against ocppoc cluster

## Current Status: 📝 PLANNED
Not yet deployed - template only

Semantic Validation Commands

# Check status claims against cluster (manual)
oc get pods -n ai-platform | grep <service>
oc get agents.kagent.dev -n ai-platform

# Cross-reference with ground truth
diff <(grep "Status:" docs/code-map/services/*.md) <(cat docs/agents/catalog.md)

--verify-claims Flag

When running /doc coverage --verify-claims:

1. Extract all "Status: X" claims from docs 2. Query deployment state (oc get pods, oc get agents) 3. Report mismatches as CRITICAL 4. Flag stale validation dates (>30 days) as WARNING

---

Anti-Patterns