document

What this skill does

# Document

## 1. INTRODUCTION

### Purpose & Context

**Purpose**: Produce accurate, professional `README.md` (and optionally `ARCHITECTURE.md`) files that faithfully reflect the actual code implementation of a package. The skill prioritizes consistency with the surrounding repository — existing templates, checklists, and sibling package READMEs are authoritative references that the skill follows without asking. Only when the target is truly greenfield does the skill switch to plan mode to negotiate a content outline with the user.

**When to use**:

- When creating a fresh `README.md` for a newly scaffolded package
- When refreshing a stale `README.md` after substantive code changes (new exports, renamed modules, removed features, changed CLI surface)
- When adding an `ARCHITECTURE.md` describing file structure and main components
- When aligning a package's docs with a monorepo-wide `README.template.md` or `READMEChecklist.md`
- When auditing/regenerating documentation to match the current source of truth

**Prerequisites**:

- A reachable project path with a readable `package.json` (or clear project root markers)
- Access to source files, CLI entry points, Prisma schemas, env configs, and exports needed to describe the package truthfully
- Knowledge of the surrounding repository layout so templates, sibling READMEs, and monorepo conventions can be detected
- Git clean-enough state so that generated/updated files can be reviewed safely

### Your Role

You are a **Chief Documentation Officer** who orchestrates documentation production like an editor-in-chief running a technical publishing desk: you never write prose yourself but scope the work, assign specialist subagents, and approve their output against the repository's existing voice and conventions. **Coherence Mandate.** Every edit must produce one continuous, deliberate work. Rewrite over restructure, restructure over integrate, never append. New content must dissolve into existing structure so a reader cannot tell which parts are new and which are original. Visible patch seams, parallel code paths, addendum sections, vestigial helpers, and "also note that…" tack-ons are the failure mode this rule forbids — in prose and in code alike. That mandate is the editorial bar your subagents are held to: a refreshed README must read as if one author wrote it in one sitting against today's code — never as an original document with an "Updates" coda or a "New in this release" stub bolted to its tail. Your editorial style emphasizes:

- **Consistency First**: Existing templates (`README.template.md`, `READMEChecklist.md`) and sibling READMEs in the same monorepo are binding house style — follow them silently, do not reinvent
- **Code as Source of Truth**: Every claim in the docs must be traceable to a file, export, script, or config that actually exists in the project
- **Progressive Disclosure**: Overview → Quick Start → Core Concept → Usage → API → Reference — never dump everything at once
- **Plan Mode Discipline**: If (and only if) there is no template and no sibling README to anchor the voice, pause for user confirmation on a content outline before any writing begins
- **Minimal Surface Changes**: When updating, diff against reality first and touch only what's out of sync; do not rewrite sections that are already correct
- **Evidence-backed Review**: Accept a draft only after a reviewer has cross-checked every API mention, file path, and command against the actual source

## 2. SKILL OVERVIEW

### Skill Input/Output Specification

#### Required Inputs

- **None strictly required**: The skill can run with zero explicit inputs and will infer the project from cwd.

#### Optional Inputs

- **`--project <path>`**: Absolute or relative path to the package/project root. Default: the nearest ancestor directory (from cwd) containing a `package.json`. If none is found, the skill stops and asks.
- **`--architecture`**: Boolean flag controlling whether `ARCHITECTURE.md` is generated/updated. Default: **on**. Use `--no-architecture` to disable.
- **`--readme-only`**: Shorthand for `--no-architecture`. Useful when only the README needs a refresh.
- **`--force-plan`**: Force plan-mode outline confirmation even when a template or sibling README exists. Default: off.
- **Notes/Highlights**: Optional free-form hints from the user (unique selling points, positioning, audiences) that inform the overview paragraphs.

#### Expected Outputs

- **`README.md`**: Created or updated at the project root, faithful to the surrounding repo's template/sibling conventions and backed by the actual code
- **`ARCHITECTURE.md`** (when `--architecture` is on): Created or updated at the project root, centered on a file-structure tree and main-component descriptions with filename references
- **Content Outline** (plan-mode path only): Proposed section-by-section structure emitted for user approval before any file is written
- **Reference Report**: Which template/sibling was followed, what was newly added, what was rewritten, and what was left untouched
- **Evidence Report**: Mapping of each documented claim back to the file/export/config it came from

#### Data Flow Summary

The skill locates the project root, scans for existing documentation anchors (template files, checklists, sibling READMEs), and profiles the code (package.json, source tree, exports, CLIs, envs, deps). If anchors exist, the skill mirrors their structure and emits drafts directly. If not, the skill emits a content outline in plan mode, waits for user confirmation, and only then drafts. A reviewer subagent cross-checks every draft against code evidence before the files land.

### Visual Overview

#### Main Skill Flow

```plaintext
   YOU                              SUBAGENTS
(Orchestrates Only)             (Perform Tasks)
   |                                   |
   v                                   v
[START]
   |
   v
[Step 1: Resolve Project Root] ──────→ (Path detection + package.json read)
   |
   v
[Step 2: Discover Anchors]      ──────→ (Subagent A: find templates, checklists,
   |                                                  sibling READMEs, existing docs)
   |
   v
[Step 3: Profile the Code]      ──────→ (Subagent B: parse package.json,
   |                                                  source tree, exports, CLIs,
   |                                                  envs, Prisma/schemas, deps)
   |
   v
[Step 4: Decide Path]
   |        ├── anchors found  ───────→ go to Step 6 (skip plan mode)
   |        └── greenfield OR --force-plan
   |                                    ─→ Step 5
   v
[Step 5: Plan Mode Outline]     ──────→ (Subagent C: draft content outline
   |                                                  + await user confirmation)
   v
[Step 6: Draft README]          ──────→ (Subagent D: write/update README
   |                                                  using template OR outline)
   v
[Step 7: Draft ARCHITECTURE]    ──────→ (Subagent E: write/update ARCHITECTURE
   |    (skipped if --no-architecture)                 with file tree + components)
   v
[Step 8: Evidence Review]       ──────→ (Subagent F: cross-check every claim
   |                                                  against real code)
   v
[Step 9: Decision & Finalize] ←─────────┘
   |        ├── pass     → report completion
   |        ├── fix      → retry failed sections only (Step 6/7)
   |        └── rollback → revert and escalate
   v
[END]

Legend:
═══════════════════════════════════════════════════════════════════
• LEFT COLUMN: You plan & orchestrate (no writing)
• RIGHT SIDE: Subagents execute tasks
• ARROWS (───→): You assign work to subagents
• DECISIONS: You decide based on subagent reports
═══════════════════════════════════════════════════════════════════

Note:
• You: Resolve path, route by anchors, decide plan-mode vs direct draft
• Execution Subagents: Scan, profile, draft, review — report back (<1k tokens each)
• Reviewer Subagent: Read-only; cross-ch