---
name: bigstack-docs
version: 0.1.0
description: |
  Documentation generation and maintenance for existing codebases.
  Scans for gaps, generates or updates README, architecture docs,
  and API documentation following existing project conventions.
allowed-tools:
  - Bash
  - Read
  - Glob
  - Grep
  - Edit
  - Write
  - AskUserQuestion
---

{{PREAMBLE}}

# /bigstack-docs — Documentation for Existing Codebases

Generate, update, and maintain documentation for an existing codebase.

## Workflow

### Step 1: Inventory Existing Docs

```bash
# Find all documentation files
find . -name "README.md" -o -name "ARCHITECTURE.md" -o -name "DESIGN.md" \
  -o -name "CONTRIBUTING.md" -o -name "CHANGELOG.md" -o -name "API.md" \
  -o -name "*.mdx" 2>/dev/null | grep -v node_modules | grep -v .git | sort
```

```bash
# Check for doc generators
ls docs/ doc/ documentation/ 2>/dev/null
ls docusaurus.config.* mkdocs.yml .vitepress/ 2>/dev/null
```

### Step 2: Identify Gaps

Compare what exists against what a well-documented project should have:

| Document | Status | Priority |
|----------|--------|----------|
| Root README.md | exists / missing / stale | High |
| Architecture overview | exists / missing / stale | High |
| API documentation | exists / missing / stale | Medium |
| Contributing guide | exists / missing / stale | Low |
| Changelog | exists / missing / stale | Medium |

A document is "stale" if:
- It references files, functions, or APIs that no longer exist
- Its "last updated" date is >6 months old
- The code has significantly diverged from the described behavior

### Step 3: Generate/Update

For each gap, ordered by priority:
1. Read the relevant code to understand current behavior
2. Follow existing documentation style and conventions
3. Generate or update the document
4. Cross-reference with existing docs to avoid duplication
5. **Add Mermaid diagrams liberally** (see Step 3a)

**Key principles for existing codebases:**
- Don't assume you know the full architecture — document what you can verify
- Preserve existing documentation structure and voice
- Mark uncertain sections with `<!-- TODO: verify -->`
- Include code references (`file:line`) so docs stay traceable
- Prefer a diagram over prose when describing structure, flow, or state

### Step 3a: Diagrams (Mermaid)

GitHub renders Mermaid natively inside fenced ```mermaid blocks. Reach for a
diagram *first*, and use prose to annotate it — not the other way around.
A well-placed diagram replaces paragraphs of description.

**Default to including at least one diagram per non-trivial document.** Most
architecture, API, and onboarding docs benefit from 2–4 diagrams. If a section
describes components, flows, states, or relationships, it probably wants a
diagram.

Pick the right diagram type for the job:

| What you're describing | Diagram type |
|------------------------|--------------|
| System components and their relationships | `flowchart` / `graph` |
| Request/response or message flow between services | `sequenceDiagram` |
| Lifecycle, status transitions, feature flags | `stateDiagram-v2` |
| Data model, tables, foreign keys | `erDiagram` |
| Release timelines, rollout phases | `gantt` or `timeline` |
| Directory layout or module hierarchy | `flowchart` (top-down) |
| Class / type relationships | `classDiagram` |
| User-facing flows and decision points | `flowchart` with decision nodes |

Example — architecture overview:

~~~markdown
```mermaid
flowchart LR
  Client -->|HTTPS| API[API Gateway]
  API --> Auth[(Auth Service)]
  API --> Worker[Worker Queue]
  Worker --> DB[(Postgres)]
  Worker --> Cache[(Redis)]
```
~~~

Example — request flow:

~~~markdown
```mermaid
sequenceDiagram
  participant U as User
  participant API
  participant DB
  U->>API: POST /orders
  API->>DB: INSERT order
  DB-->>API: ok
  API-->>U: 201 Created
```
~~~

Example — state machine:

~~~markdown
```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Published: publish()
  Published --> Archived: archive()
  Archived --> [*]
```
~~~

Diagram quality rules:
- Keep each diagram focused on one idea — split rather than cram
- Label edges with the action or protocol (`POST /foo`, `emits`, `reads`)
- Use consistent node shapes across a document (e.g. `[(...)]` for datastores)
- Verify rendering by reading the raw Mermaid — don't invent syntax
- If a diagram would have >15 nodes, it's probably two diagrams

### Step 4: Validation

```bash
# Check for broken internal links in markdown
grep -rn '\[.*\](\.\/\|\.\.\/\|#)' *.md **/*.md 2>/dev/null | while read line; do
  # Extract link target and verify it exists
  echo "$line"
done
```

### Step 5: Summary

Report what was created/updated and what still needs manual review.

{{CONFIDENCE_CALIBRATION}}