Template: templates/frame.architecture.md

# {{title}}

_The overarching shape of the product as a built system. When the detail outgrows a single file, expand into an optional `Arch/` folder and keep this doc as the map that points into it._

## Shape

_The system in one breath: the major pieces and how they fit. A paragraph or a simple sketch. Enough that a newcomer can hold the whole in their head before reading any spec._

## Components

_The named parts and what each is responsible for. One line to a short paragraph each. Boundaries matter more than internals here; this is the map, not the territory._

## Data and flow

_What moves through the system and where it lives. The path a request, a record, or an event takes from edge to store and back._

## Boundaries and dependencies

_Where this system ends and others begin. Outside services, platforms, and integrations it leans on. The seams where it could break or be swapped._

Template: templates/frame.audience.md

# {{title}}

_Who the product is for, and how each kind of person interacts with it differently. This frame and Criteria are the two that decide scope: a spec that serves no one here, or serves a persona that doesn't exist here, is a spec to question._

## Audience

_Who uses this product, in a paragraph or two. The whole population it is built for, described plainly. Not segmented yet, just the answer to "who is this for."_

## Personas

_How each kind of person interacts differently. One short block of prose per persona, never a table or a headshot-and-demographics card. The point is the difference: what this persona comes for, how they reach for the product, what they ignore. A persona earns its place here only when it interacts in a way the others do not._

### Persona name

_What this person is here to do and how they go about it._

### Persona name

_The next persona, described by how it differs from the one above._

Template: templates/frame.criteria.md

# {{title}}

_The frame that decides and audits scope: what the product can afford, what it is trying to be, and by when. When scope creeps, it creeps past this doc._

## Budget

_How the work gets financed and what that buys. The rough money or resource envelope: funded how, spending against what, for how long the runway lasts. Enough to tell whether a given spec is affordable._

## Scope Objectives

_What the product is aiming to be at this level: a prototype, an MVP, a production product, a platform. The objective sets the ceiling on scope. State it plainly so specs can be checked against it._

## Timeline

_The limits time imposes. Hard dates, milestones, or seasons that bound the work. What must exist by when, and what that forces to wait._

## Parameters & Variables

_The large-scale factors that move scope — the things that, if they change, change what is feasible or sensible to build. An integration going live, a development partner coming on or dropping off, a funding milestone, a platform deadline, a key hire. Name each one and what it would change._

Template: templates/frame.market.md

# {{title}}

_Where the product sits in its marketplace, why it is not just another one of many, and how it is intended to make money._

## Landscape

_The market this product enters: the category it lives in, and the substitutes people reach for today. An honest picture of how crowded it is._

## Competitors

_The specific products and alternatives you are up against — named. For each, a line on what it does well and where it leaves a gap. Include the "do nothing" or "use a spreadsheet" substitutes, not just the direct rivals._

## Positioning & Differentiators

_Where this product sits, and the specific thing that makes it not interchangeable with the rest. Not a slogan: the concrete difference a user would feel. If you cannot name it, that is the most important thing this doc has surfaced._

## Who it is for and against

_The slice of the market this product wins, and the competitors it wins it from. The customer it serves better than anyone, stated plainly._

## Earning Capabilities

_How the product is intended to make money. The revenue model: what is charged, to whom, on what cadence. Where the money comes from, and what has to be true for it to work._

Template: templates/spec.full.md

# {{title}}

## Intent

_Why this exists: the problem, who has it, and what this unit is for. One or two paragraphs that stand on their own; a reader who opens only this spec learns what it is without following a link. This is the stable part: if Intent changes substantially, you probably have a different spec, not an edit to this one._

### Assumptions

_What you take as given about the problem or the world and have not confirmed. Nested under Intent because they frame it. Surface them so a guess doesn't slip into the requirements as if it were settled._

## Open Questions

_What is still unknown and needs an answer. Kept high, right after Intent, so uncertainty is seen rather than buried. When one is settled it leaves this section and becomes an Assumption, a Requirement, or a Decision; delete the section when none is open._

## Requirements

_What it does, as observable outcomes: if it isn't listed here, it isn't promised. Label each **REQ1:**, **REQ2:**, … (bold), starting at 1 in every spec and running in order with no gaps. Group them under the categories that apply as `###` sub-headings (Functional, Performance, Design, External interface, Quality attributes), the numbers running on across them. Keep each short and checkable; push rich detail into a table or sub-section it points to. Link to another spec's requirement by its label: `[Sign In REQ6](../identity/sign-in.md#req6)`._

### Functional

- **REQ1:** <!-- features, behaviors, business rules -->

### Performance

- **REQ2:** <!-- speed, throughput, response time, capacity, concurrent users -->

### Design

- **REQ3:** <!-- mandated tech, standards, regulatory rules, platform limits -->

### External interface

- **REQ4:** <!-- how it connects to users, hardware, other software, networks: UI, APIs, protocols -->

### Quality attributes

- **REQ5:** <!-- the other -ilities: reliability, security, usability, maintainability, scalability, portability -->

## Out of Scope

_What a reader might expect this spec to cover and it does not, each named and, where another spec holds it, linked there. This is where scope is held: name the neighbouring concerns one by one rather than pointing at a whole spec._

## Dependencies

_What this relies on to work, and what for: services, libraries, data, or other specs, each linked (`[Session Management](../identity/session-management.md)`). A relationship, never an order of work. The `depends_on` property is the spec-only subset of this, as links._

## Decisions

_The calls that shaped this spec and why, one line each, newest last, with the date and who made it. Append-only: a reversal is a new line, never an edit to the old one._

<!-- 2026-06-17: Dropped the SMS fallback, carrier cost. (Brenton) -->

Template: templates/spec.micro.md

# {{title}}

## Intent

_Why this exists: the problem, who has it, and what this unit is for. One or two paragraphs that stand on their own. This is the stable part: if Intent changes substantially, you probably have a different spec, not an edit to this one._

### Assumptions

_What you take as given and have not confirmed. Nested under Intent because they frame it. A micro spec almost always has some; surfacing them is half the point of writing one early._

## Open Questions

_What is still unknown and needs an answer. When one is settled it leaves this section and becomes an Assumption, a Requirement, or a Decision; delete the section when none is open._

## Requirements

_What it does, as observable outcomes: if it isn't listed here, it isn't promised. Label each **REQ1:**, **REQ2:**, … (bold), starting at 1 and running in order with no gaps. Keep each short and checkable._

- **REQ1:** <!-- the first observable outcome -->

## Out of Scope

_What a reader might expect this spec to cover and it does not, each named and, where another spec holds it, linked there._