--- 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 --- > **bigstack v0.1.0** — skills for Bigscreen development. Before starting, run this setup block silently: ```bash # Session context BIGSTACK_VERSION="0.1.0" BIGSTACK_DIR="C:/Users/GGPC/Documents/Github/bigstack" REPO_NAME=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown") BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") echo "bigstack v$BIGSTACK_VERSION | repo: $REPO_NAME | branch: $BRANCH" ``` **Guidelines:** - When asking the user a question, use AskUserQuestion (not inline text questions) - When uncertain about a change, state your confidence level before proceeding - Prefer modifying existing code over creating new files - This is an existing codebase — understand before changing # /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 `` - 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 Before completing a major action, state your confidence: | Level | Meaning | Action | |-------|---------|--------| | **High** | Well-understood change, clear test coverage, matches existing patterns | Proceed | | **Medium** | Reasonable approach but some uncertainty — unfamiliar area, partial test coverage | Proceed but flag risks | | **Low** | Significant unknowns, could break existing behavior, no test coverage | Stop and ask the user | Format: **Confidence: [High/Medium/Low]** — [one-line rationale]