Document an existing decision from code as an ADR or DES
/plugin marketplace add asermax/claude-plugins/plugin install katachi@asermax-plugins<topic>Document an existing architectural decision or design pattern from the codebase.
Topic or pattern: $ARGUMENTS
Skill to load:
Load the katachi:retrofit-existing skill for retrofit workflow.
Decision indexes:
@docs/architecture/README.md - Architecture decisions (ADRs)
@docs/design/README.md - Design patterns (DES)
Vision (if present):
@planning/VISION.md - Project context for inference
Verify:
If topic is vague, ask for clarification:
"You mentioned: [topic]
Can you point me to:
- A specific file or module that uses this pattern?
- Or describe how this decision manifests in the code?"
Read files that demonstrate the decision:
Task(
subagent_type="katachi:codebase-analyzer",
prompt=f"""
Analyze the codebase to document this decision.
## Analysis Type
decision
## Topic
{topic_description}
## Relevant Code
{code_content}
## Project Context
{vision_content if exists else "Infer from code"}
Determine if this is:
- ADR (one-time architectural choice)
- DES (repeatable pattern)
Create a draft document with:
- Context inferred from code
- Alternatives that weren't chosen (infer from what exists)
- Consequences observed in the implementation
"""
)
Based on analysis, present recommendation:
"Based on the code analysis, this appears to be a [ADR/DES]:
[If ADR]:
This is an architectural decision - a one-time choice that would be expensive
to change. Examples: database choice, framework, authentication approach.
[If DES]:
This is a design pattern - a repeatable approach used in multiple places.
Examples: error handling, logging conventions, test structure.
Do you agree with this classification, or should it be the other type?"
Show the agent's draft:
## Draft [ADR/DES]
[Draft content]
---
### Notes from Analysis
- Context inferred from: [source]
- Alternatives inferred because: [reasoning]
- Consequences observed in: [locations]
What needs adjustment?
User provides corrections:
Continue until user approves.
Check existing documents:
For ADR:
ls docs/architecture/ADR-*.md
# Determine next number: ADR-NNN
For DES:
ls docs/design/DES-*.md
# Determine next number: DES-NNN
For ADR:
Update docs/architecture/README.md:
For DES:
Update docs/design/README.md:
Write to appropriate location:
For ADR:
# ADR-NNN: [Title]
## Retrofit Note
This ADR documents an existing decision discovered in the codebase.
Decision likely made: [date from git history or "Unknown"]
---
[Rest of ADR content with status: Accepted]
For DES:
# DES-NNN: [Pattern Name]
## Retrofit Note
This DES documents an existing pattern discovered in the codebase.
Pattern established in: [files where first used]
---
[Rest of DES content]
Ask:
"Which existing features use this [decision/pattern]?
I'll update their specs/designs to reference this document."
For each affected feature, note to update:
"Decision documented:
File: docs/[architecture/design]/[ADR/DES]-NNN-title.md
Type: [ADR/DES]
Status: Accepted
The [decision/pattern] is now part of the documented framework.
Future features should:
- Reference this in their designs
- Follow this [decision/pattern] unless superseding
Would you like to:
- Retrofit another decision: /katachi:retrofit-decision <topic>
- Update a feature design to reference this: /katachi:design-feature <ID>
- Retrofit a spec: /katachi:retrofit-spec <path>"
This is a collaborative process: