explain

Explain (Decision Documentation)

Create decision records that document the reasoning behind implementation choices.

Philosophy

Good code is self-documenting for what it does. But why it does it that way? That's lost to time unless we capture it.

"Six months from now, when someone asks 'Why did we do it this way?', will there be an answer?"

The value of this skill isn't compliance—it's preserving context that makes the codebase maintainable.

Config Integration

Follow the migration preflight in references/config-migration.md, then check for .assistant-config.md in the project root.

Decisions location (in order of precedence):

1. Decisions location setting in config
2. Existing decisions/ directory
3. Existing docs/decisions/ or docs/adr/ directory
4. Default: create decisions/

If no config exists, ask the user where to store decisions or use the default.

When to Use

Run /explain after:

• Completing a significant implementation
• Making an architectural decision
• Choosing between multiple valid approaches
• Implementing something counterintuitive
• When future developers might ask "why was it done this way?"

Input

The user will provide:

• File path(s) to explain, OR
• Feature/change description, OR
• Specific question ("Why did we use X instead of Y?")

If nothing provided, explain recent uncommitted changes.

Process

1. Understand the Decisions

For the code being explained, identify:

• Key architectural choices
• Algorithm or pattern selections
• Library/dependency choices
• Trade-offs that were made
• Constraints that influenced the approach

2. Research Context

Gather context before writing:

• What patterns exist elsewhere in the codebase?
• Were there constraints from existing code?
• What does the task file or PR description say?
• What alternatives could have been used?

3. Generate File Name

Use the pattern: NNNN-short-description.md

• Check existing files in decisions directory
• Use next available number (0001, 0002, etc.)
• Keep description short (2-4 words, kebab-case)