briefkit-documenter
Create interface-first documentation using BRIEF system v3. Generate BRIEF.md files with inputs/outputs contracts, validate against spec, convert PRDs/specs to BRIEFs, and support multi-surface applications (Web/Mobile/API). Use when creating module documentation, establishing documentation standards, or documenting legacy code.
When & Why to Use This Skill
The Briefkit Documenter is a specialized tool designed to automate the creation and maintenance of interface-first documentation using the BRIEF system v3. It streamlines the technical writing process by generating agent-friendly BRIEF.md files that prioritize interface contracts over implementation details, ensuring clear communication between developers and AI agents while maintaining high documentation standards across Web, Mobile, and API platforms.
Use Cases
- New Module Documentation: Automatically analyze code boundaries and extract interface contracts to generate standardized BRIEF.md files for new features.
- Legacy Code Refactoring: Document undocumented legacy modules by inferring interfaces and using 'INFERRED' markers to highlight areas needing human verification.
- PRD to Technical Spec Conversion: Transform high-level Product Requirement Documents into actionable, structured technical documentation with defined inputs and outputs.
- Documentation Quality Assurance: Validate existing documentation against BRIEF v3 standards using multi-tier validation rules to identify missing sections or stale snapshots.
| name | briefkit-documenter |
|---|---|
| description | Create interface-first documentation using BRIEF system v3. Generate BRIEF.md files with inputs/outputs contracts, validate against spec, convert PRDs/specs to BRIEFs, and support multi-surface applications (Web/Mobile/API). Use when creating module documentation, establishing documentation standards, or documenting legacy code. |
| allowed-tools | [Read, Write, Edit, Grep, Glob] |
| version | 1.0.0 |
Briefkit Documenter
Purpose
Generate and maintain BRIEF.md files for module documentation. Creates agent-friendly, human-readable docs that prioritize interfaces over implementation.
When to Use
- Creating module documentation (new or existing code)
- Converting PRDs/specs to BRIEFs
- Validating existing documentation
- Setting up repository-wide documentation standards
- Multi-surface applications (Web/Mobile/API)
Quick Start
Generate a BRIEF
1. Analyze module code and boundaries
2. Generate BRIEF.md with all required sections
3. Mark uncertain content with INFERRED
4. Validate against rules
5. Request human review
Required Sections
Every BRIEF must have these sections in order:
# <Module> — BRIEF(title)- Purpose & Boundary
- Interface Contract (Inputs → Outputs)
- Dependencies & Integration Points
- Work State (Planned / Doing / Done)
- SPEC_SNAPSHOT (YYYY-MM-DD)
- Decisions & Rationale
- Local Reference Index (if submodules)
- Answer Pack (YAML)
See SPECIFICATION.md for complete specifications.
Validation
Tier-1 Blockers: Missing BRIEF, Interface Contract, INFERRED markers, invalid YAML, >200 lines
Tier-2 Warnings: Missing/stale snapshot, broken links, missing Answer Pack
Full rules in references/SPECIFICATION.md
Resources
Core References
PATTERNS.md- Practical patterns and templatesEXAMPLES.md- 8 complete real-world examplesPHILOSOPHY.md- Philosophy and methodologySPECIFICATION.md- Authoritative v3 specification
Example Workflows
1. New Module Documentation
User: "Document the auth module"
→ Analyze code → Extract interfaces → Generate BRIEF → Validate → Deliver
2. Legacy Code Documentation
User: "Document this undocumented module"
→ Infer from code → Heavy INFERRED markers → Generate BRIEF → Request review
More workflows in PATTERNS.md
Quick Reference Searches
Find content quickly using grep:
# In SPECIFICATION.md
grep "^### [0-9]\." references/SPECIFICATION.md # List numbered sections
grep "Required.*:" references/SPECIFICATION.md # Find required fields
grep "Tier-[12]" references/SPECIFICATION.md # Find validation tiers
# In PATTERNS.md
grep "^## .* Pattern$" references/PATTERNS.md # List all patterns
grep "DO\|DON'T" references/PATTERNS.md # Find do/don't lists
# In EXAMPLES.md
grep "^### Example [0-9]:" references/EXAMPLES.md # List inline examples (2 quick-start)
ls references/examples/*.md # List specialized examples (6 files)
grep "Multi-Surface" references/EXAMPLES.md # Find multi-platform examples
# In PHILOSOPHY.md
grep "Interface-First" references/PHILOSOPHY.md # Find interface-first mentions
grep "^### Why" references/PHILOSOPHY.md # Find rationale sections
# Universal search
grep -r "validation" references/ # Find validation info
grep -r "INFERRED" references/ # Find INFERRED marker guidance
Philosophy
Interface-first: Document WHAT before HOW. See PHILOSOPHY.md for deep dive.
Next Steps
- Try: Create a BRIEF for an existing module
- Validate: Check existing BRIEFs
- Learn: Read EXAMPLES.md for patterns
- Deep dive: Explore PHILOSOPHY.md
Version: 1.0.0 | Based on: BRIEF System v3