<!-- 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

No scaffold script ships with this skill — explore manually, then fill the
template from the structure below:

```bash
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
```

---

## Report Modes

| Mode | Time | Depth | Use When |
|------|------|-------|----------|
| **Quick Scan** | 10 min | Entry + types + flow | Orientation, PR context |
| **Standard** | 30 min | Full template | Onboarding, docs |
| **Deep Dive** | 1+ hr | + diagrams, all paths | Audits, major decisions |

### 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

```markdown
# [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

| Don't | Do |
|-------|-----|
| Stop at understanding | Always produce artifact |
| Vague descriptions | Include `file:line` refs |
| Skip data flow | Trace end-to-end |
| One giant report | Match depth to purpose |
| Assume knowledge persists | Write it down now |

---

## Integration

### With New Projects

On a fresh clone, start the report by hand: copy the section structure from
this reference into `ARCHITECTURE.md`, then fill it from manual exploration
(Quick Start above). There is no auto-scaffold script.

### With Other Skills

| After using... | Consider... |
|----------------|-------------|
| codebase-archaeology | Producing this report to persist findings |
| multi-pass-bug-hunting | Adding "Known Issues" section |
| cross-project-pattern-extraction | Noting patterns in "Notes & Gotchas" |

---

## References

| Topic | File |
|-------|------|

## Scripts

Shipped with the doc skill (`skills/doc/scripts/`):

| Script | Purpose |
|--------|---------|
| `scripts/audit-oss-docs.sh` | Audit OSS documentation coverage by tier |
| `scripts/validate.sh` | Self-check the doc skill package structure |

## Subagents

| Subagent | Purpose |
|----------|---------|
| `subagents/explorer.md` | Parallel exploration for large codebases |
# Example Architecture Reports

## Example 1: beads_rust (CLI Tool)

Real report from a local-first issue tracker:

```markdown
# 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:**
```bash
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)

```markdown
# 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

| Report Type | Time | Depth | Use When |
|-------------|------|-------|----------|
| **Quick Scan** | 10 min | Entry points + key types | Orientation, PR review |
| **Standard** | 30 min | Full template | Onboarding, documentation |
| **Deep Dive** | 1+ hr | + sequence diagrams, all flows | Architecture review, audits |

### 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

| Entry | Location | Purpose |
|-------|----------|---------|
| CLI main | `src/main.rs:15` | Parses args via clap, dispatches commands |
| HTTP router | `src/routes/mod.rs:1` | Sets up axum/express routes |
| [Add more] | `path:line` | Description |

---

## Key Types

| Type | Location | Purpose |
|------|----------|---------|
| `TypeName` | `src/model.rs:10` | Core domain object representing X |
| `Config` | `src/config.rs:5` | Runtime configuration loaded from file/env |
| `Storage` | `src/storage.rs:1` | Persistence layer abstraction |
| [Add more] | `path:line` | Description |

---

## 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

| Dependency | Purpose | Critical? |
|------------|---------|-----------|
| SQLite (rusqlite) | Local persistence | Yes |
| reqwest | HTTP client for external APIs | No |
| tokio | Async runtime | Yes |
| serde | Serialization | Yes |
| [Add more] | Purpose | Yes/No |

---

## Configuration

| Source | Location/Example | Priority |
|--------|------------------|----------|
| Environment var | `APP_CONFIG=/path/to/config.toml` | 1 (highest) |
| Config file | `~/.config/app/config.toml` | 2 |
| CLI flag | `--config /path` | 3 |
| Default | Hardcoded in `src/config.rs:50` | 4 (lowest) |

**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

| Type | Location | Count |
|------|----------|-------|
| Unit tests | `src/**/*.rs` (inline) | ~XXX |
| Integration | `tests/integration/` | ~XX |
| E2E | `tests/e2e/` | ~X |

**Running Tests:**
```bash
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]*

# De-Slopify — Docs Prose Pass

> Make documentation read like a careful human wrote it. This is a **docs
> quality** method under [`doc`](../SKILL.md), not a general writing skill and
> not a standalone AgentOps skill.

Use it from `doc` (required for `--mode=readme` generate/rewrite) so READMEs and
other repo docs stay concrete, scannable, and free of LLM prefab.

Use this reference from `doc` (especially `--mode=readme`) before reporting
completion.

> **Core insight #1:** You cannot do this with regex or a script. It requires a
> manual, line-by-line read. A linter catches a fraction; the rest is judgment.
>
> **Core insight #2:** Slop is a thinking defect wearing a fluent surface.
> Alignment trains models toward the *mode* of human preference, so prose goes
> prefab. Lexical diversity can rise while conceptual diversity falls. Swapping
> blacklist words is necessary and not sufficient. A real pass removes the
> prefab *and* checks that something specific is still present (the additive
> floor below).

## THE PROMPT — full

```
Read the complete text line by line and remove AI-slop tells. You MUST do this by
reading and recasting each line manually — not with regex or find-replace.

WORD-LEVEL TELLS (recast on sight):
- Prefabricated phrases / dying metaphors: "move the needle," "navigate the
  landscape," "at its core," "unlock," "delve," "tapestry," "testament to,"
  "in today's fast-paced world." Cut or re-image with something concrete.
- Verbal false limbs: "make contact with" → meet, "give rise to" → cause,
  "has the ability to" → can.
- Zombie nouns on light verbs: "make a decision" → decide, "the implementation
  of X" → we built X. Judgment, not a ban.
- Copula avoidance: "serves as / boasts / features" where plain "is/are" works.
- Lead-ins: "Here's why," "Here's the thing," "It's worth noting," "Let's dive
  in" — just say it.

STRUCTURAL TELLS:
- Explicit contrast "it's not X, it's Y" / "not only X but also Y." Worst on the
  headline. Cap ≤1 per piece, at an earned mid-body pivot. Prefer two facts the
  reader collides.
- Reflexive rule of three ("fast, simple, and powerful"). Cap ~1 per 500 words.
- Manufactured punchy fragment: short contentless beat ("It isn't new."
  "Simple."). Fold or cut. A short sentence with a real claim stays.
- Manufactured cadence: 3–4 same-shape sentences stacked. Break the symmetry.
- Elegant variation: "notes → explains → observes." Force-repeat the plain word.
- Inflated importance + trailing "-ing" tail: cut to the quiet specific claim.

THE DEEP ONE:
- Each paragraph needs one concrete particular (name, number, path, command) and
  at least one non-obvious idea. Fluent generality is still slop.

Then read the whole thing aloud. Fix every drone, stumble, and breath failure.
```

## THE PROMPT — quick

```
Remove AI-slop: prefab phrases, verbal false limbs, zombie nouns, copula
avoidance, "here's why"/"dive in" lead-ins, explicit "not X, it's Y" (≤1, never
on the headline), reflexive rule-of-three, stacked same-shape sentences, elegant
variation. Each paragraph needs one concrete particular. Read aloud. Recast
manually — no regex.
```

## Subtractive pass

1. Prefab phrases and dying metaphors → concrete subject-specific wording.
2. Verbal false limbs → live verbs.
3. Zombie nouns → verbs where it restores a live verb.
4. Copula avoidance → plain is/are.
5. Metadiscourse / signposting ("Moreover," "In this section," "In conclusion") → cut.
6. Lead-ins and forced enthusiasm → delete; say the thing.
7. Explicit contrast cap (never on the headline).
8. Rule-of-three cap.
9. Manufactured fragment and manufactured cadence.
10. Elegant variation → repeat the plain word; vary ideas.
11. Lower rhetorical temperature ("pivotal," "transformative," "groundbreaking").
12. Vague attribution ("studies show") → name the source or cut.
13. Mechanical formatting tells (gratuitous bold, optimistic "despite challenges" closers).

### Em-dash: use-pattern, not frequency

Do not count dashes and call frequency the signal (it flips by model generation).
Flag the *mechanical append* — a clause fused with a dash where a comma, colon,
period, or two sentences would do. Recast that pattern.

### Dictation sources

Strip filler (um, like, you know), verbal runways, and false starts. Keep the
resolved claim. Do not rebuild a self-repair as "not X, it's Y."

## Additive floor

After cuts, confirm:

- One concrete particular per paragraph
- Muddy sentences rewrite the thought (clutter is unfinished thinking)
- One non-obvious idea per section
- Sentence-length variance (build long, land short)
- Read-aloud gate last

Subtraction alone yields clean, bloodless prose that still reads generated.

## Before / after

**Prefab + inflation**
Before: `Our platform serves as a comprehensive solution that unlocks transformative value.`
After: `The platform turns raw logs into a weekly report.`

**Contrast on the headline**
Before: `It's not a linter — it's a complete code-quality system.`
After: `This checks types, lint, complexity, and the build on every push.`

**Lead-in**
Before: `We chose Rust for this component. Here's why: performance matters.`
After: `We chose Rust because the hot path runs 40M times a day and GC pauses showed up in the p99.`

## Density, not brevity

"Omit needless words" means every word tells — not that every sentence is short.
Do not chop a long sentence that earns its length into stubs.

## What not to "fix"

- Technical accuracy
- Necessary headers and lists
- Thoroughness (being complete is not slop; padding is)
- Code examples (focus on prose)

## When to run

- Before publishing a README, doc, or release note
- After any AI-assisted writing session
- During `doc --mode=readme` generate/rewrite (required) and validate (flag findings)

## Required from Doc readme mode

After writing or rewriting `README.md`, run the full prompt above on the exact
file and apply fixes before Step 5 deterministic checks. On `--validate`, report
residual slop tells as evidence; do not silently rewrite unless the caller asked
for rewrite.

# Doc default mode — code/API docs, code-maps, coverage/validate

> **Provenance:** This is the default-mode workflow **moved verbatim** out of
> `skills/doc/SKILL.md` (generic-craft trim).
> Steps 1-7 below — grep for undocumented functions, stamp function/class markdown,
> compute coverage, write a report — are frontier-trivial: a capable model does them
> correctly with no skill payload. The skill's durable value is the references-led
> `--mode=readme` and `--mode=oss` modes, which stay in `SKILL.md`.
> This file is retained so the default mode still has a full spec to follow.

Given a Doc command and target:

## Step 1: Detect Project Type

```bash
# 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:
```bash
# 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:
```bash
# 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:**
```markdown
## function_name

**Purpose:** What it does

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

**Returns:** What it returns

**Example:**
```python
result = function_name(arg1, arg2)
```

**Notes:** Any important caveats
```

**For Classes:**
```markdown
## ClassName

**Purpose:** What this class represents

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

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

**Usage:**
```python
obj = ClassName()
obj.method1()
```
```

## Step 4: Create Code-Map (if requested)

**Write to:** `docs/code-map/`

```markdown
# 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/scratch/doc/YYYY-MM-DD-<target>.md`

```markdown
# 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>
```

## 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

| Command | Action |
|---------|--------|
| `discover` | Find undocumented features |
| `coverage` | Check documentation coverage |
| `gen [feature]` | Generate docs for specific feature |
| `all` | Update all documentation |
| `validate` | Check docs match code |

## 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/scratch/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

| Problem | Cause | Solution |
|---------|-------|----------|
| Coverage calculation inaccurate | Grep pattern doesn't match all code styles | Adjust pattern for project conventions. For Python, check for `async def` and class methods. For Go, check both `func` and `type` definitions. |
| Generated docs lack examples | Missing context about typical usage | Read existing tests to find usage patterns. Check README for code samples. Ask user for typical use case if unclear. |
| Discover command finds too many items | Low existing documentation coverage | Prioritize by running `discover` on specific subdirectories. Focus on public API first, internal utilities later. Use `--limit` to process in batches. |
| Validation shows docs out of sync | Code changed after docs written | Re-run `gen` command for affected features. Consider adding git hook to flag doc updates needed when code changes. |

# Documentation Generation Templates

## CODING: Code-Map Template

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

```markdown
---
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

```markdown
---
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 label — ../replace/with/real-doc.md`
- `Link label — ../replace/with/real-doc.md`

## References

- External sources
```

---

## OPS: Helm Chart Template

```markdown
# [Chart Name]

## Overview

[Description from Chart.yaml]

## Quick Start

```bash
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:

```markdown
---
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:

```markdown
<!-- 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 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.**

| File | Purpose | Template |
|------|---------|----------|
| `LICENSE` | Legal terms for usage | Apache 2.0, MIT, etc. |
| `README.md` | First impression, quick start | Project-type specific |
| `CONTRIBUTING.md` | How to contribute | Fork/PR workflow |
| `CODE_OF_CONDUCT.md` | Community standards | Contributor Covenant |

### 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

```bash
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.**

| File | Purpose | When Critical |
|------|---------|---------------|
| `SECURITY.md` | Vulnerability reporting | Always |
| `CHANGELOG.md` | Version history | Versioned releases |
| `AGENTS.md` | AI assistant context | AI-assisted development |
| `.github/ISSUE_TEMPLATE/` | Structured issue reports | Public issue tracker |
| `.github/PULL_REQUEST_TEMPLATE.md` | PR checklist | Active contributions |

### 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

```bash
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.**

| File | Purpose | Recommended When |
|------|---------|------------------|
| `docs/QUICKSTART.md` | Detailed getting started | Complex setup |
| `docs/ARCHITECTURE.md` | System design | Non-trivial codebase |
| `docs/CLI_REFERENCE.md` | Command documentation | CLI tools |
| `docs/CONFIG.md` | Configuration options | Configurable software |
| `docs/TROUBLESHOOTING.md` | Common issues | Production software |
| `docs/FAQ.md` | Frequently asked questions | Recurring questions |
| `examples/README.md` | Example index | Multiple examples |

### Recommendation Matrix

| Project Characteristic | Recommended Docs |
|------------------------|------------------|
| CLI tool | CLI_REFERENCE.md, QUICKSTART.md |
| Kubernetes operator | ARCHITECTURE.md, CONFIG.md |
| Library | API.md, examples/ |
| Complex config | CONFIG.md, TROUBLESHOOTING.md |
| Large codebase | ARCHITECTURE.md, INTERNALS.md |

### Audit Check

```bash
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.**

| Category | Files |
|----------|-------|
| **API** | `docs/API.md`, OpenAPI spec |
| **Helm** | `docs/VALUES.md`, upgrade guides |
| **Operator** | CRD references, RBAC docs |
| **Protocol** | Wire format, versioning |
| **MCP** | Server setup, tool documentation |

---

## Scoring Guide

| Score Range | Status | Action |
|-------------|--------|--------|
| Tier 1 < 4 | Incomplete | Add missing required files |
| Tier 1 = 4, Tier 2 < 3 | Basic | Add standard files |
| Tier 1 = 4, Tier 2 >= 3 | Standard | Consider Tier 3 |
| All tiers complete | Comprehensive | Maintain and update |

---

## 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 optional reference guidance for the Doc skill's OSS mode; 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

| Command | Action |
|---------|--------|
| `audit` | Check which OSS docs exist/missing |
| `scaffold` | Create the requested missing standard files |
| `scaffold [file]` | Create specific file |
| `refresh` | Update existing docs within the accepted request; existing authorization is sufficient |
| `validate` | Check docs follow best practices |

---

## Phase 0: Project Detection

```bash
# 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)

| File | Purpose |
|------|---------|
| `LICENSE` | Legal terms |
| `README.md` | Project overview |
| `CONTRIBUTING.md` | How to contribute |
| `CODE_OF_CONDUCT.md` | Community standards |

### Recommended Files (Tier 2 - Standard)

| File | Purpose |
|------|---------|
| `SECURITY.md` | Vulnerability reporting |
| `CHANGELOG.md` | Version history |
| `AGENTS.md` | AI assistant context |
| `.github/ISSUE_TEMPLATE/` | Issue templates |
| `.github/PULL_REQUEST_TEMPLATE.md` | PR template |

### Optional Files (Tier 3 - Enhanced)

| File | When Needed |
|------|-------------|
| `docs/QUICKSTART.md` | Complex setup |
| `docs/ARCHITECTURE.md` | Non-trivial codebase |
| `docs/CLI_REFERENCE.md` | CLI tools |
| `docs/CONFIG.md` | Configurable software |
| `examples/` | Complex workflows |

Full tier definitions: [oss-documentation-tiers.md](oss-documentation-tiers.md).

---

## Subcommand: scaffold

### Template Selection

| Project Type | Focus |
|--------------|-------|
| `cli` | Installation, commands, examples |
| `operator` | K8s CRDs, RBAC, deployment |
| `service` | API, configuration, deployment |
| `library` | API reference, examples |
| `helm` | Values, dependencies, upgrading |

Per-type content templates: [oss-project-types.md](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

```markdown
# Agent Instructions

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

## Quick Reference

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

## Verification evidence

Run the documentation checks relevant to the created files and report their
commands, results, and unchecked scope. Doc does not commit, push, release, or
decide completion; repository policy and the caller own those transitions.

---

## 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:**
- Update or overwrite existing content outside the authorized request, including through `refresh`
- 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

| Problem | Cause | Solution |
|---------|-------|----------|
| Generated docs feel generic | Project signals too sparse | Add concrete repo context (commands, architecture, workflows) |
| Existing docs conflict | Legacy text diverges from current behavior | Reconcile with current code/process and mark obsolete sections |
| Contributor path unclear | Missing setup/testing guidance | Add explicit quickstart and validation commands |
| Open-source handoff incomplete | Session-end workflow not reflected | Add landing-the-plane and release hygiene steps |

# Project Types Reference

> Documentation patterns by project category.
> Templates adapt to project type for relevant content.

## Type Detection

```bash
#!/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

| File | Priority | Content Focus |
|------|----------|---------------|
| `README.md` | Required | Installation (brew, go install), quick start |
| `docs/CLI_REFERENCE.md` | High | All commands with flags |
| `docs/QUICKSTART.md` | High | First-run experience |
| `docs/CONFIG.md` | Medium | Config files, env vars |
| `docs/TROUBLESHOOTING.md` | Medium | Common errors, fixes |
| `examples/` | Medium | Usage examples |

### README Template Key Sections

```markdown
## Installation

```bash
# 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

```bash
<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

| File | Priority | Content Focus |
|------|----------|---------------|
| `README.md` | Required | What it manages, quick install |
| `docs/ARCHITECTURE.md` | High | Controllers, reconciliation |
| `docs/CONFIG.md` | High | CRD spec fields |
| `SECURITY.md` | High | RBAC, pod security |
| `docs/TROUBLESHOOTING.md` | Medium | Common issues |

### README Template Key Sections

```markdown
## Installation

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

Or with Helm:
```bash
helm install <name> <repo>/<chart>
```

## CRDs

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

## Quick Start

```yaml
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

```markdown
## 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

| File | Priority | Content Focus |
|------|----------|---------------|
| `README.md` | Required | Installation, basic values |
| `docs/VALUES.md` | High | All values documented |
| `docs/UPGRADING.md` | Medium | Version migration |

### README Template Key Sections

```markdown
## Installation

```bash
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

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

---

## Type: library-go

**Go Libraries**

### Detection Signals
- `go.mod` present
- No `cmd/` directory
- Public package exports

### Recommended Documentation

| File | Priority | Content Focus |
|------|----------|---------------|
| `README.md` | Required | Installation, basic usage |
| `docs/API.md` | High | Public API reference |
| `examples/` | High | Usage patterns |

### README Template Key Sections

```markdown
## Installation

```bash
go get <module>
```

## Usage

```go
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

| File | Priority | Content Focus |
|------|----------|---------------|
| `README.md` | Required | Installation, basic usage |
| `docs/API.md` | High | Public API reference |
| `examples/` | High | Usage notebooks/scripts |

### README Template Key Sections

```markdown
## Installation

```bash
pip install <package>
# or
uv pip install <package>
```

## Usage

```python
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:

```markdown
## Installation

```bash
# 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

| File | Priority | Content Focus |
|------|----------|---------------|
| `README.md` | Required | Navigation, purpose |
| `CONTRIBUTING.md` | High | How to contribute docs |
| `docs/index.md` | High | Main entry point |

---

## Language Detection

```bash
#!/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)

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

### Python (click/typer)

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

---

## Test Command Detection

```bash
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

| Signal | Weight | Detection |
|--------|--------|-----------|
| `services/` directory | +3 | `[[ -d services ]]` |
| `src/` directory | +2 | `[[ -d src ]]` |
| `pyproject.toml` or `package.json` | +2 | Config file exists |
| `docs/code-map/` directory | +3 | Code-map docs exist |
| >50 Python/TypeScript files | +2 | File count |
| FastAPI/Express routes | +2 | `@app.get`, `router.` patterns |

**Threshold**: Score >= 5 = Likely CODING repo

---

## INFORMATIONAL Signals

| Signal | Weight | Detection |
|--------|--------|-----------|
| `docs/corpus/` directory | +3 | Knowledge corpus |
| `docs/standards/` directory | +2 | Standards docs |
| >100 markdown files | +3 | High doc count |
| No `services/` or `src/` | +2 | Not a code repo |
| Diataxis structure | +2 | `tutorials/`, `how-to/`, `reference/`, `explanation/` |

**Threshold**: Score >= 5 = Likely INFORMATIONAL repo

---

## OPS Signals

| Signal | Weight | Detection |
|--------|--------|-----------|
| `charts/` directory | +3 | Helm charts |
| `apps/` or `applications/` | +2 | ArgoCD apps |
| >5 `values.yaml` files | +3 | Multi-environment Helm |
| `config.env` files | +2 | Config rendering |
| ArgoCD manifests | +2 | `Application` kind |

**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

| Type | `/doc all` | `/doc discover` | `/doc coverage` |
|------|------------|-----------------|-----------------|
| CODING | Generate code-maps | Find services, endpoints | Entity coverage |
| INFORMATIONAL | Validate all docs | Find corpus sections | Link validation |
| OPS | Generate Helm docs | Find charts, configs | Values coverage |

# 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:

| Check | Pass condition |
|---|---|
| Evidence | Claims cite code, commands, or source docs. |
| Brevity | Each section earns its place. |
| Operator value | The next reader can act without rediscovery. |
| No filler | Generic AI prose is removed. |

---

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

# README Craft — Gold-Standard README Generation

> Generate a README that converts skimmers into users and satisfies deep readers, then run deterministic documentation checks and return factual evidence to the caller.

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

## Quick Start

```bash
/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:

| Concern | Answer it |
|---------|-----------|
| What does it touch? | Files created/modified, hooks registered |
| Does it exfiltrate? | Telemetry, network calls, data leaving the machine |
| Permission surface | Shell commands, config changes, git behavior modifications |
| Reversibility | How to disable instantly, how to uninstall completely |

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

```bash
ls README.md 2>/dev/null
```

**Mode detection:**
- `--validate` + README exists → skip to Step 5 (deterministic review only)
- `--rewrite` + README exists → read existing, use as context for rewrite
- README exists, no flags → ask:
  - "Rewrite — regenerate with gold-standard patterns"
  - "Validate — check the existing README without rewriting it"
  - "Cancel"
- No README exists → proceed to Step 2 (generate from scratch)

### Step 2: Gather Context

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

```bash
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:

```markdown
<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 4b: Docs prose pass (required)

Read [de-slopify.md](de-slopify.md) and run the full docs-prose prompt on the
exact `README.md` you just wrote. Apply fixes in place. Manual line-by-line
recast only — no regex pass. Do not report the README complete until this pass
has run.

On `--validate` only: inspect for residual prefab/slop tells and record them as
evidence; do not rewrite unless the caller asked for `--rewrite`.

### Step 5: Deterministic checks

Run `bash skills/doc/scripts/validate.sh` and inspect the anti-pattern table
below against the exact README. Record concrete matches, checked scope, and
anything the local environment could not check. These results are evidence,
not a semantic verdict.

Do not start Council, rewrite the README again, or decide what happens after a
finding. The caller may supply the README and these results to Validate as part
of an exact candidate.

### Step 6: Report

```
## README Evidence

**File:** README.md
**Sections:** {count}
**Patterns applied:** {list which of the 8 patterns were relevant}
**Checks:** {commands and factual results}
**Unchecked:** {scope not examined}

{List concrete findings without approval or next-action language}
```

---

## Anti-Patterns to Detect

When rewriting or validating, flag these:

| Anti-Pattern | Detection | Fix |
|-------------|-----------|-----|
| **Flywheel echo** | Core value prop stated 3+ times | State once, demonstrate once |
| **Framework-first** | Opens with methodology name, not problem | Rewrite lead as problem statement |
| **Guru tone** | "What I learned", "This is what makes X different" | Strip, let the tool speak |
| **Jargon before definition** | Domain terms used before they're explained | Define on first use or use plain language |
| **Buried trust info** | Security/permissions info below the fold | Move near install |
| **No visible uninstall** | Uninstall not findable within 10 seconds | Add near install block |
| **Install scatter** | Same install command in 3+ locations | One hero install, one canonical reference |
| **Theory before try** | Architecture/philosophy before examples | Reorder: examples first, theory in details |
| **Claim without evidence** | "Best", "different", "unique" without demo | Replace with concrete example or remove |
| **AI slop prose** | Prefab phrases, "not X, it's Y" on the lead, "here's why," metronomic cadence | Run [de-slopify.md](de-slopify.md); recast manually |

---

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| README validator cannot run | A required local tool or path is unavailable | Record the command failure and unchecked scope; do not claim the check passed |
| Generated README has no trust block | No trust concerns were selected during the interview (step 3f answered "None of the above") | Report the mismatch when the tool does run hooks, modify config, or make network calls |
| `<details>` blocks render as raw HTML on GitHub | Missing blank line after `<summary>` tag or before `</details>` | This mode enforces the formatting rule, but manual edits may break it. Ensure a blank line after every `<summary>...</summary>` line and before every `</details>` |
| Interview keeps asking questions the project manifest already answers | The manifest file format is not recognized by the context-gathering step | Ensure your project has a standard manifest (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`) in the repo root |
| Anti-pattern detection flags false positives on rewrite | Some content patterns trigger heuristic detection even when intentional | Report the exact match as heuristic evidence and let the caller judge it |

# Documentation Validation Rules

## Coverage Metrics by Type

| Type | Key Metric | Target | How Measured |
|------|-----------|--------|--------------|
| CODING | Entity Coverage | >= 90% | Documented services / total services |
| CODING | Signpost Accuracy | 100% | Referenced functions exist |
| INFORMATIONAL | Frontmatter Valid | >= 95% | Required fields present |
| INFORMATIONAL | Links Valid | 100% | All internal links resolve |
| OPS | Values.yaml Coverage | >= 80% | Documented keys / total keys |
| OPS | Golden Completeness | 100% | Required sections present |

---

## INFORMATIONAL Validation

No standalone validator script ships with this skill. Run the checks below
manually — for doc-file presence coverage use the shipped
`skills/doc/scripts/audit-oss-docs.sh`; for link/orphan/path checks write a
short throwaway Python script in the target repo (not bash: bash loops are
O(n*m) and time out on large repos, while Python processes 350+ files in
seconds with cleaner regex extraction).

### 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/

### 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 |

===================================================================
```

---

## Semantic Validation (CODING repos)

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

### Semantic Metrics

| Check | How | Target |
|-------|-----|--------|
| Status Accuracy | Compare "Status: X" to deployment state | 100% |
| Claim Verification | Cross-ref with ground truth file | 100% |
| Validation Freshness | Status includes date | < 30 days |

### Ground Truth Pattern

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

| Domain | Ground Truth | Pattern |
|--------|--------------|---------|
| Agents | `docs/agents/catalog.md` | Reference via link |
| Images | `charts/*/IMAGE-LIST.md` | Reference via link |
| Config | `values.yaml` | Generate docs from source |

### Status Validation

Valid status formats:

```markdown
## 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

```bash
# 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

| DON'T | DO INSTEAD |
|-------|------------|
| Sample 20 files, declare "healthy" | Scan ALL files |
| Say "healthy" with broken links | Report exact issue counts |
| Skip validation for "organized" repos | Validate regardless |
| Use bash loops on large repos | Use Python validator |
| Claim "deployed" without verification | Validate against cluster first |
| Duplicate ground truth data | Reference authoritative file |
| Omit validation dates | Include "Validated: DATE against SOURCE" |