ADR Drafting

You are drafting an Architecture Decision Record because the user (or you) has proposed a deviation from constitutional defaults.

When to invoke

Trigger this skill on any of:

• Microservice extraction proposal
• Database-per-service proposal
• Dropping or omitting a foreign key
• Putting transactional truth in Neo4j or any non-Postgres store
• Skipping RLS on a tenant-scoped table
• Skipping the outbox for a domain event
• Destructive migration (column drop, table rewrite, type change with rewrite)
• Denormalization without measured evidence
• Use of the deprecated @modelcontextprotocol/server-postgres
• Any explicit override of a § N principle

Pre-flight

1. Read .specify/memory/constitution.md and identify which sections (§ N) the deviation touches.
2. Read .specify/memory/architecture-decisions.md. Find the next ADR number (max + 1, zero-padded to 4 digits).
3. Search for an existing ADR on the same topic:
   • If one exists and the user wants the opposite decision → new ADR with Supersedes: ADR-NNNN
   • If one exists and the user wants to refine it → propose amending in place (bump status notes, add a new ## Amendment YYYY-MM-DD section)
   • If none exists → proceed to draft a new ADR

ADR Template

Create the file at .specify/architecture-decisions/ADR-NNNN-<kebab-title>.md using the following structure. If .specify/architecture-decisions/ADR-TEMPLATE.md exists on disk, read and use it instead of the inline template below.

# ADR-NNNN: <Short imperative title>

**Status:** Proposed  
**Date:** YYYY-MM-DD  
**Supersedes:** *(ADR-NNNN if applicable, else omit)*  
**Constitutional sections affected:** § N, § M

## Context

Describe the situation that makes this decision necessary. Include:
- What the system currently does
- What problem or pressure is driving the proposed change
- Any measured evidence (query times, error rates, load figures) if relevant

## Decision

State the decision clearly in one or two sentences.
> We will / We will not …

## Consequences

### Positive
- …

### Negative / Trade-offs
- …

### Risks
- …

## Alternatives Rejected

| Alternative | Reason rejected |
|-------------|----------------|
| … | … |

## Migration Path

Step-by-step plan to move from the current state to the decided state,
including rollback procedure if the migration can be reversed.

1. …
2. …

## Validation Criteria

Measurable conditions that confirm the decision was implemented correctly
and is producing the expected outcome.

- [ ] …
- [ ] …

## Constitutional Sections Affected

For each affected section, quote the relevant principle and explain how
this ADR complies with or consciously overrides it.

**§ N — <Section name>:**  
> *Quoted principle text*  
This ADR [complies because … / overrides because …]

Enforcement Gate

Do not perform any implementation work related to the proposed deviation until the ADR file exists on disk with Status: Proposed (or higher).

After drafting, tell the user:

ADR-NNNN has been written to .specify/architecture-decisions/ADR-NNNN-<title>.md with status Proposed. Review it, update the status to Accepted or Rejected, then ask me to continue. I will not proceed with the underlying change until the ADR is at least Proposed and saved.

Example — Constitutional Sections Affected (key section to get right)

The section most likely to need care is Constitutional Sections Affected. Here is a worked illustration from a denormalization ADR:

## Constitutional Sections Affected

**§ 4 — Normalization:**  
> *Transactional truth lives in normalized Postgres tables.*  
This ADR overrides § 4 for point-in-time pricing preservation. The canonical
product record remains normalized; the snapshot is a historical audit artifact.

**§ 7 — Audit:**  
> *All mutations must be attributable and reversible.*  
This ADR complies: the snapshot is written once at order creation and never
mutated, preserving a clear audit trail.

For a fuller worked example of a complete ADR, see .specify/architecture-decisions/ADR-EXAMPLE.md if it exists on disk.

Post-draft Steps

1. Write the ADR file to .specify/architecture-decisions/ADR-NNNN-<title>.md.
2. Append a summary line to .specify/memory/architecture-decisions.md:

   | ADR-NNNN | <Short title> | Proposed | YYYY-MM-DD | § N, § M |

3. Inform the user of the file path and the enforcement gate (see above).
4. Wait for the user to confirm the ADR status before proceeding with any implementation work.