ADR + Spec Gate — Mandatory Entry Point for Development

Overview

Every new project and every non-trivial feature must pass through a dual-gate entry point before any code is written. This skill enforces the discipline of explicit design documentation before implementation.

The two required artifacts:

1. Specification (Spec) — What to build, why, and how.
2. Architecture Decision Record (ADR) — Why non-obvious design choices were made.

This gate prevents common failures: discovering broken assumptions mid-build, remaking decisions that were already made weeks earlier, and projects that only "exist" in chat and dissolve when the conversation ends.

1. Specification

A specification is a document that fully describes a feature or system at the design level, sufficient for another engineer (or AI agent) to continue implementation without asking the original author questions.

Minimal Specification Template

# <Feature/System Name> Specification

## Objective
What problem does this solve? (1-2 sentences)

## Scope
What is IN scope?
- Explicit feature list
- Boundaries

What is OUT of scope?
- What will NOT be built now (and why)

## Requirements
- User-visible requirements
- Non-functional requirements (performance, security, scale)
- Constraints (regulatory, technical, business)

## Proposed Architecture
- High-level design
- Key components and interactions
- Data model (if applicable)
- External dependencies

## Inputs and Outputs
- What does the system accept?
- What does it produce?
- Format and validation rules

## Error Handling
- What can fail?
- How should failures be handled?
- Recovery strategy

## Success Metrics
- How will we know this was built correctly?
- Quantifiable measures if possible

Spec Location

• Default: docs/<feature-name>-spec.md or a dedicated SPEC.md in the root.
• For existing features: add a new section to the living spec rather than fragmenting.

Spec Quality Check

• ] Spec is detailed enough for another engineer to continue without asking questions?
• ] Scope boundaries are explicit (not just implicit)?
• ] Non-functional requirements are named (performance, scale, security)?
• ] Error cases are described, not swept under "error handling TBD"?
• ] Success metrics are measurable or at least checkable?

If any of these is false, the spec is incomplete. Incomplete specs are useless because they move the ambiguity into code, where it multiplies.

2. Architecture Decision Record (ADR)

An ADR is a lightweight record of a design decision, its rationale, and its consequences. Not every decision needs an ADR — only non-obvious choices.

When is a decision non-obvious?

• It has reasonable alternatives that were considered and rejected.
• It trades off one quality concern (e.g., performance) for another (e.g., maintainability).
• It involves a technology choice with downstream consequences (database, framework, language, protocol).
• It's not a "there's only one way to do this" decision.

Minimal ADR Template

# ADR-NNN: <Decision Title>

**Date:** YYYY-MM-DD  
**Status:** Proposed | Accepted | Superseded | Deprecated  
**Author:** <name>

## Context

Why did we need to decide this? What problem or constraint forced the decision?

## Decision

What did we decide to do? Be specific and concrete.

## Rationale

Why this choice over the alternatives? What trade-off did we accept?

## Alternatives Considered

1. **Alternative A**: Why we rejected it
2. **Alternative B**: Why we rejected it

## Consequences

What are the downstream effects of this choice?
- Positive: What becomes easier or better?
- Negative: What becomes harder or more costly?

## Related Decisions

- Links to other ADRs or specs affected by this choice

ADR Location

• Default: docs/adr/ADR-NNN-title.md or a single architecture-decisions.md file.
• Number sequentially so they're easy to reference.

ADR Quality Check

• ] Decision is explicitly stated (not vague)?
• ] Context explains why the decision was necessary (not arbitrary)?
• ] Alternatives are named and compared (not just straw-manned)?
• ] Consequences are realistic, not optimistic?
• ] Status is set (Proposed, Accepted, Superseded, or Deprecated)?

An ADR is not a sales pitch. It's a record of what was decided and why, including downsides. If it reads as "this is the best," it's incomplete — all choices have trade-offs, and the ADR should name them.

Gate: Entry Checklist

Before writing any code, verify:

• ] Spec exists and is detailed enough for another engineer to continue?
• ] Non-obvious design decisions have ADRs?
• ] Status of all ADRs is set (not left as "TBD")?
• ] Spec and ADRs are in version control or a shared location (not in chat)?

If all are true, proceed. If any are false, write the missing documents first.

Exceptions?

No. This applies to:

• New projects (always)
• New features in existing projects (if non-trivial)
• Significant refactors (if they involve design changes)
• Infrastructure changes (if they involve tooling or topology decisions)

Size is not an exception. An ADR can be 5 lines. A spec can be a single page. The act of writing is what forces clarity. Skipping it because "it's small" is the exact scenario that produces forgotten decisions and rework months later.

Anti-Patterns (Prohibited)

• Spec "in the author's head" → Not a spec. It exists only in the next chat session as a question.
• ADR "we'll document later" → It never happens. Document when you make the decision, in the same session.
• Feature code starting with vague intent ("I'll make a module that does X") → Stops when scope collides with reality.
• Skipping gate because "it's quick" → The gate is not a bottleneck; it's an accelerant. Unclear design is the bottleneck.
• ADR that hides downsides → All choices have trade-offs. Hiding them does not make them go away; it just makes them a surprise later.

Implementation Workflow

1. Open a fresh spec document (empty file, clear name).
2. Fill in each section, enforcing specificity.

• "Inputs": name types, formats, validation rules.
• "Error handling": list at least 3 failure modes and how each is handled.
• "Success metrics": quantify or describe measurable behavior.

1. Identify non-obvious design decisions (technology, architecture, data model, flow).
2. For each decision, write a short ADR (or add to a living architecture-decisions.md).

• Name the alternatives you considered.
• Explain why this choice won.
• Name the trade-off (what you're giving up).

1. Review with another engineer or reviewer (or rubber-duck: read it aloud to yourself).

• If they ask "but why X instead of Y?", that's an ADR that's missing.
• If they ask "what does the spec mean by this?", that's a spec section that needs clarity.

1. Update status to Accepted (for ADRs) when the review is done.
2. Commit spec and ADRs to version control (they're now immutable history).
3. Begin implementation, using the spec and ADRs as your contract with the future.

What This Enables

• Clarity for future handoff — another engineer (or AI agent) reads the spec and ADRs, not the chat.
• Replayable decisions — when "why did we choose X?" arises weeks later, the answer is in the ADR, not the author's memory.
• Faster implementation — constraints and scope are explicit, so implementation doesn't derail on unstated assumptions.
• Reduced rework — design flaws are caught before code, not discovered mid-implementation.
• Audit trail — decisions and their rationale are permanently recorded, not lost when the chat scrolls away.

Validation

How to know the spec is good: another engineer can read it, understand the full scope and constraints, and implement it without asking you questions.

How to know the ADRs are good: someone unfamiliar with the project reads them and understands both what was decided and why it was the better choice than the alternatives.

If either document fails this test, incomplete.

References and Further Reading

• ADR Guide — Nygard, M. "Documenting Architecture Decisions." Accessible via https://adr.github.io/
• Specification by Example — Gojko Adzic. Practical techniques for writing specifications that test themselves.
• Architecture Decision Records at Scale — Common patterns for organizations managing 50+ ADRs across multiple teams.

This skill pairs well with other design-first disciplines (RFC, Technical Design Docs, Threat Models). Use them together to shift complexity left — from implementation to design, where it's cheapest to fix.