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.json contains docsLocation

• 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).