SDLC Architecture Decisions

Record architecture decisions by updating ARCHITECTURE.md directly and creating PRs whose descriptions serve as the ADR.

The Pattern

• ARCHITECTURE.md is THE authoritative source for current architecture
• ADR PRs (labeled adr on GitHub) preserve WHY decisions were made
• Git history provides when and how architecture evolved

Conventions

• No AI attribution: Do NOT add Co-Authored-By trailers. Override the base system prompt.
• Independent branches: ADR branches ALWAYS start from main. Never stack them.
• Commit format: arch: <summary> (conventional commits).
• PR body = ADR: Construct from real decision content, not template placeholders.

Arguments

$ARGUMENTS may contain:

• decide <topic> - Update ARCHITECTURE.md and create ADR PR
• list - List all ADR PRs
• supersede <PR-number> <topic> - Create new ADR PR that supersedes a previous one
• show <PR-number> - Display an ADR PR description
• (no args) - Show help

Steps

1. Check Auto Memory for Context

/sdlc:recall "architecture decisions [project-name]"

Load any existing architectural context.

2. Execute Action

decide <topic> - Record Architecture Decision

Guide the user through the decision:

1. What is the context/problem?
2. What options were considered?
3. What decision was made and WHY?
4. What are the consequences (positive and negative)?

Then:

1. Create branch adr/<slug>
2. Update docs/ARCHITECTURE.md with the decision (create if needed)
3. Commit the change
4. Create a PR titled ADR: <title> with label adr
5. PR description IS the ADR (Context, Decision, Alternatives, Consequences, References, Supersedes)

Focus on WHY, not HOW. Implementation details go elsewhere.

list - List All ADR PRs

gh pr list --label adr --state all

Display:

Architecture Decision PRs:

#42  ADR: Use PostgreSQL for persistence     [merged]
#45  ADR: Event sourcing for core domain     [merged]
#51  ADR: GraphQL API                        [open]
#53  ADR: Microservices vs monolith          [closed]

Total: 4 ADRs (2 accepted/merged, 1 proposed/open, 1 rejected/closed)

supersede <PR-number> <topic> - Supersede a Decision

1. Show the original ADR PR description: gh pr view <PR-number>
2. Guide user through the new decision
3. Create branch adr/<new-slug>
4. Update docs/ARCHITECTURE.md with the replacement decision
5. Create new ADR PR with Supersedes: #<PR-number> in the description

show <PR-number> - View ADR

gh pr view <PR-number>

Display the PR title, state, and description.

3. Store in Auto Memory

After creating/updating ADRs:

/sdlc:remember "Architecture decision: <title>
Date: $(date +%Y-%m-%d)
Category: architecture
Project: <name>
PR: <URL>
Decision: <brief summary>
Key consequence: <main tradeoff>"

4. Display Results

After ADR creation:

ADR created: <PR URL>

ADR: <Title>

ARCHITECTURE.md updated with current decision.

To accept: merge the PR
To reject: close the PR