| name | explain-decisions |
| description | Answer "why" questions about architectural choices using arkive/architecture.json. |
| trigger | User asks "why did we choose X?", "why this database?", "why not use Y?", "explain the architecture", or clicks "Why this?" in the web viewer. |
Explain Decisions
Behavior
-
Read architecture data:
- Via MCP: read
architecture://decisions resource
- Via file: read
decisions array from arkive/architecture.json
-
Find the relevant decision: Search by topic, decision, or relatedServices matching the user's question.
-
Explain with this structure:
## {topic}
**Decision:** {decision}
**Why:** {rationale}
**Alternatives considered:**
- **{alternative.name}**: Rejected because {alternative.whyNot}
**Related services:** {relatedServices}
-
If no matching decision exists:
- Check services, connections, and stack for relevant context
- Explain what's available
- Suggest recording a formal decision:
- Via MCP: "I can call
record_decision to document this choice"
- Via file: "I can add a decision entry to
arkive/architecture.json"
-
Connect to the bigger picture: After explaining, briefly mention how this decision relates to other architectural choices in the project.
MUST NOT
- Do NOT fabricate rationale that isn't in arkive/architecture.json
- Do NOT guess at alternatives that weren't recorded