SDD Decisions & Assumptions

docs/sdd-guidelines.md §1.4: "A system can have perfect existence links yet lose integrity if decision reasoning is lost."

When to Document

Decisions (DEC-NNN)

Assumptions (ASM-NNN)

Format by Significance

Instructions

Creating a Decision Record

1. Assess significance — Does it warrant a file or inline?

1. For High significance:

``bash # Templates are in this skill's templates/ directory # Copy to your project's spec/decisions/ mkdir -p spec/decisions # Then create from template structure (see templates/DEC-template.md) ``

1. Fill required fields:

- Choice (what was decided) - Alternatives (what was rejected) - Rationale (why this choice) - Impacts (what this affects)

1. Link from artifact:

``markdown @rationale: DEC-003 ``

Creating an Assumption Record

1. Assess risk — Formal record or inline?

1. For High-risk:

``bash # Copy template structure to your project mkdir -p spec/assumptions # Then create from template structure (see templates/ASM-template.md) ``

1. Fill required fields:

- Assumption (what we assume true) - Basis (why we believe it) - Risk (what if wrong) - Invalidation triggers (conditions that would falsify)

1. Link from artifact:

``markdown @assumes: ASM-002 ``

Quick Reference

Inline Rationale (Medium/Low)

## Token Bucket Algorithm

`@derives:` REQ-005
`@rationale:` Chose token bucket over sliding window — O(1) memory per key 
              vs O(n) for sliding window. Critical for 10K+ concurrent keys.

Inline Assumption (Low-risk)

## API Gateway

`@derives:` REQ-003
`@assumes:` Single-region deployment (if multi-region, need distributed rate limiting)

Reference to Formal Record

## Authentication Flow

`@derives:` REQ-AUTH-001
`@rationale:` DEC-002 (OAuth2 vs custom auth)
`@assumes:` ASM-001 (IdP availability)

Directory Structure

spec/
├── decisions/
│   ├── DEC-001.md    # Architecture decisions
│   ├── DEC-002.md
│   └── ...
└── assumptions/
    ├── ASM-001.md    # High-risk assumptions
    └── ...

ID Conventions

Superseding Decisions

When a decision is replaced:

---
id: DEC-005
supersedes: DEC-002
---

# Use JWT instead of Session Tokens

## Context

DEC-002 chose session tokens. New requirements (REQ-015: stateless API) 
invalidate that decision.

...

Update old decision:

---
id: DEC-002
status: superseded
superseded_by: DEC-005
---

Assumption Invalidation

When assumption proves false:

1. Update ASM record:

``yaml status: invalidated invalidatedat: 2025-01-17 invalidatedby: "Production showed 3 regions needed" ``

1. Find all @assumes: ASM-NNN references

1. Re-verify each dependent artifact

1. Create new assumption or decision if needed

Verification Checklist

• Non-obvious choices have @rationale
• High-risk assumptions have ASM-NNN records
• All DEC/ASM records have required fields
• Superseded decisions marked with superseded_by
• Invalidated assumptions tracked

Templates

• [templates/DEC-template.md](templates/DEC-template.md)
• [templates/ASM-template.md](templates/ASM-template.md)

References

• docs/sdd-guidelines.md §1.4 Supporting Records
• docs/sdd-philosophy.md §2.2 Decision