write-document

Write Document (BMAD)

Create high-signal technical documentation that serves as an expert collaborator for both humans and AI. This skill enforces the BMAD principles to prevent context rot and ensure architectural durability.

Distinct from edit-document: Use this skill to create a document that does not yet exist. Use edit-document when a document already exists and needs restructuring, clarity, or prose improvements.

HARD GATE — Every document must have a clear "Reason for Existence." If a document doesn't provide actionable leverage for a caller or test, do not create it.

The BMAD Principles

Principle	Execution
Bold	Make strong assertions. Define clear boundaries and "Never" rules. No "it might" or "usually."
Minimal	High-density, low-filler. Circuit Breaker: If the file exceeds 300 lines or the session exceeds 20 turns, you MUST run terse-mode and compact state before saving.
Actionable	Link every doc to a verifiable outcome. Architectural Docs: Verify via Gherkin features (specs/verifications/features/) or grep-based structure checks (grep -c "pattern" file) that prove the design's constraints are present.
Durable	Design for the long-term. Scalability: Use "Nested Indexing"—root files link to module-level GEMINI.md indexes; do not list individual sub-files in the root.

Process

1. Identify the Artifact Type & Scope

Choose the correct BMAD-BigPowers artifact:

• Decision Record (ADR): For "Why" decisions (saved to specs/adr/).
• Context Map: For system-wide architectural mapping (specs/tech-architecture/tech-stack.md).
• Technical Guide: For "How-to" with verification (saved to <module>/REFERENCE.md).
• Behavioral Feature: Gherkin-style compliance specs (saved to specs/verifications/features/).
• Project README: Project-facing documentation (saved to README.md at project root).

Cross-Cutting Concerns: If a doc affects multiple modules, place the authoritative source in the lowest common ancestor directory and use "Delegates" (one-line pointers) in sub-directories to maintain the Single Source of Truth without violating the Stepdown Rule.

2. Draft with Semantic Velocity

STREAM CONTINUITY — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent.

Write the document focusing on "Expert Collaboration":

• Instructions over Descriptions: Tell the reader (human or AI) exactly how to interact with the system.
• Provenance Links: Link to ADRs, Issues, or Commits to preserve intent.
• The Stepdown Rule: Information should descend exactly one level of abstraction. If a root doc needs to explain a leaf-level detail, it must point to a sub-index first.

Quick README (Project READMEs only)

1. Ask: "Project name? One-sentence description?"
2. Generate README.md at project root using the template in REFERENCE.md — no TOC, no second interview round.
3. Fill gaps from CLAUDE.md / AGENTS.md commands if available (prefer AGENTS.md); use TODO markers otherwise.
4. Output and suggest edit-document for polish.

→ verify: test -f README.md && [ "$(grep -c '^## ' README.md)" -ge 7 ]

3. Apply the 94% Quality Gate

Before finalizing, audit the document against these red flags:

• [ ] Filler Language: Are there pleasantries or "I hope this helps"? (Delete them).
• [ ] Ambiguity: Are there "usually," "often," or "it depends" without specific conditions?
• [ ] Dead Ends: Does the document end without a "Next Step" or "Verification" command?
• [ ] Shallow Content: Does it restate the code without explaining the intent or contracts?

4. Sync and Organize

• Big Powers Hierarchy: Place the document in the correct tier (Global -> Project -> Sub-directory). Project READMEs are an exception — they go to project root (README.md), not specs/.
• Nested Indexing: If adding a module-level doc, ensure the module's GEMINI.md is updated. If the module's index is new, add it to the root GEMINI.md.
• Sync: Run scripts/sync-skills.sh if the document is a SKILL.md or affects generated artifacts.

Rules

• Minimalism is a requirement: If a document can be a 5-line table, do not make it a 5-line essay.
• Verifiable outcomes: Every technical document must include at least one verify: command. For architecture, this can be a grep or run_shell_command that validates the existence of required files or patterns.
• No speculative docs: Do not write documentation for features that do not exist yet unless explicitly doing elaborate-spec.

Suggest next skill: audit-code or sync-skills.sh.

---

Project README Template

Combined from dbader/readme-template and jehna/readme-best-practices. No TOC.

Navigation

Lines	Section
1	Title
5–40	Navigation
41–42	Sections
43–54	1. Title + Badges
55–60	2. Tagline
61–64	3. Description
65–67	4. Prerequisites
68–75	Prerequisites
76–78	5. Installation
79–89	Installation
90–92	6. Usage
93–102	Usage
103–105	7. Features
106–113	Features
114–116	8. Configuration
117–125	Configuration
126–128	9. Development Setup
129–139	Development
140–142	10. Running Tests
143–152	Tests
153–155	11. Contributing
156–164	Contributing
165–167	12. Changelog
168–172	Changelog
173–175	13. Links
176–181	Links
182–184	14. License
185–191	License
192–194	15. Credits (optional)
195–199	Credits
200–202	Verify

Sections

1. Title + Badges

# Project Name

![License](https://img.shields.io/badge/License-MIT-yellow.svg)
![npm version](https://img.shields.io/npm/v/your-package.svg)

Fill badges from CLAUDE.md stack info if available. Default to license + version badges.

2. Tagline

> One-line description of what this project does and why it matters.

3. Description

2-3 paragraphs: what problem it solves, who it's for, and what makes it different.

4. Prerequisites

## Prerequisites

- **Runtime**: Node.js v18+ (from CLAUDE.md)
- **Package manager**: npm (or pnpm/yarn)

Auto-fill from CLAUDE.md commands section when possible.

5. Installation

## Installation

```bash
npm install -g your-package
# or
npx your-package

Prefer npx one-shot if applicable; list global install as alternative.

### 6. Usage

```markdown
## Usage

```bash
your-command --help
your-command do-something

Include the most common 1-2 commands. Link to full docs if they exist.

### 7. Features

```markdown
## Features

- Feature 1: short description
- Feature 2: short description

3-6 bullet points of what the project does. Derived from the project's purpose.

8. Configuration

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `VAR_NAME` | `value` | What it controls |

Use TODO markers if unknown.

9. Development Setup

## Development

```bash
git clone <repo-url>
cd project
npm install

Auto-fill from CLAUDE.md `Run` and `Build` commands.

### 10. Running Tests

```markdown
## Tests

```bash
npm test
npm run lint

Auto-fill from CLAUDE.md `Test` and `Lint` commands.

### 11. Contributing

```markdown
## Contributing

1. Fork the repo.
2. Create a feature branch (`git checkout -b feature/my-thing`).
3. Commit changes (`git commit -am 'Add my thing'`).
4. Push (`git push origin feature/my-thing`).
5. Open a Pull Request.

12. Changelog

## Changelog

See [CHANGELOG.md](../../CHANGELOG.md) or [Releases](https://github.com/user/repo/releases).

13. Links

## Links

- Repository: https://github.com/user/repo
- Issue tracker: https://github.com/user/repo/issues

14. License

## License

MIT — see [LICENSE](../../LICENSE) for details.

Detect from CLAUDE.md or project LICENSE file.

15. Credits (optional)

## Credits

Built with [bigpowers](https://www.npmjs.com/package/bigpowers).

Verify

After generation, run: grep -c "^## " README.md — expect ≥ 7 section headings.