bonfire-document
Document Topic
Create reference documentation for $ARGUMENTS.
Outcome
Complete reference documentation that helps developers understand a system, feature, or pattern in the codebase. The doc should enable someone unfamiliar with the code to:
- Understand what it does and why it exists
- Find the relevant files quickly
- Understand how it works at a conceptual level
- Avoid common pitfalls
Acceptance Criteria
The doc file must contain these sections:
| Section | Purpose |
|---|---|
## Overview |
What this is and why it matters |
## Key Files |
Important files with their roles |
## How It Works |
Conceptual explanation of flow/behavior |
## Gotchas |
Edge cases, pitfalls, things to watch out for |
Additional sections are welcome (Architecture, Examples, Related Topics) but these four are required.
Quality signals:
- File paths are accurate and exist in the codebase
- Explanations match actual code behavior
- Gotchas reflect real issues (not hypothetical concerns)
Constraints
Context Isolation
Research happens in an isolated subagent context to preserve main context.
| Phase | Agent | Model | Why |
|---|---|---|---|
| Research | codebase-explorer |
inherit | Fast exploration without polluting main context |
| Writing | writer |
inherit | Synthesis in isolation with full research context |
Use the Task tool with the appropriate agent. The subagents have user-invocable: false so they're only accessible via Task.
No Interview Required
Unlike specs, documentation is based purely on codebase research. The code is the source of truth.
File Locations
- Config:
<git-root>/.bonfire/config.jsoncontainsdocsLocation - Default:
.bonfire/docs/if not configured - Naming:
<topic>.md(kebab-case, e.g.,authentication-flow.md)
Verification
After writing, verify the doc contains all 4 required sections. If incomplete:
- Warn user what's missing
- Offer: proceed / retry / abort
Session Context
After writing, add a reference to the doc in <git-root>/.bonfire/index.md under Key Resources.
Completion
After verification, confirm doc creation and offer options:
- Add more detail to any section
- Document related topics
- Proceed with other work
Guidance (Not Rules)
These patterns tend to work well, but adapt as needed:
Research before writing - Let the codebase inform the structure.
Show your work - Tell user what you're doing: "Exploring codebase...", "Writing documentation..."
Fallback gracefully - If subagent fails, do the work in main context. Warn user but don't stop.
Large codebases - Explorer may need multiple passes. Offer to continue if findings seem incomplete for the topic.
Follow the code - Document what the code actually does, not what comments claim or what you assume.
Writer context - When invoking the writer agent, specify document type as "doc" so it uses the correct format.
Anti-Patterns
Don't document assumptions - If you can't find it in the code, don't write about it.
Don't over-abstract - Concrete file paths and function names are more useful than vague descriptions.
Don't skip verification - Subagents can produce partial output. Always check.
Don't write tutorials - This is reference documentation (how it works), not a guide (how to use it).