Thanks for subscribing. This is everything from our issues you can put to work this week, in one place, plus the PRD, technical design, and feature spec templates Mike uses when agents do the building.
Copy any of it, change it, make it yours. Each checklist links back to the issue it came from if you want the reasoning behind it.
Part 1: Checklists
Picking your first agent workflow
From Agentic AI Is an Operating Model Change. Ask these five questions about each candidate workflow:
What business or customer outcome gets better?
Where are people spending time on repetitive judgment, coordination, or looking things up?
Which decisions can an agent assist with now, recommend later, and possibly make on its own eventually?
What does an acceptable failure look like, and where does a person stay accountable?
Do we use it, compose it, or build it?
What every team shipping agents needs
Also from Issue 01:
A clear identity and scoped permissions for each agent and each tool call
Human escalation paths for high-impact decisions
Traceability across prompts, tools, data sources, outputs, and actions
Offline and online evaluations tied to real failure modes
Kill switches, rate limits, budget caps, and approval thresholds
Monitoring for quality, safety, latency, cost, and business outcomes
Running it as an operating experiment
Pick one high-value workflow with measurable pain and manageable risk.
Form a small, accountable pod that pairs engineering strength with real domain expertise.
Decide whether to use, compose, or build.
Put evaluation, observability, access controls, and human escalation in place before you scale.
Measure whether outcomes improved. Don’t report activity, demo counts, or model usage as progress.
Protect the pipeline of people who will run this in five years.
Reuse what worked for the next workflow.
How much governance does this work need?
From You will spend the time. Choose where. Ask two questions: what does it cost if it’s wrong, and how fast can you catch it and roll it back?
High cost, fast to roll back: moderate plan, strong outcome checks.
High cost, slow to roll back: heavy plan, governance in the loops, a defined way to validate outcomes.
Low cost, fast to roll back: light plan. Let outcome checks and rollback carry it.
Low cost, slow to roll back: light plan, but fix the feedback loop before adding more agents.
Before the work starts:
Classify it on the grid above and set your governance level from where it lands.
Write the problem down first, then the path.
Write the use cases and user stories the outcome will be checked against.
Get the plan approved by someone who’s built this kind of thing before.
While the agents work:
Put governance where the architecture or outcomes are changing. Ease off where they’re stable.
Watch for rubber stamps. If approvals come back fast and nothing ever gets sent back, people stopped reading.
At the outcome:
Check the result against the use cases, not just green tests.
Run the newcomer test: could someone new to the project read the plan and quickly tell whether the outcome is right?
Building a team culture for uncertain work
From AI Teams: Hold the Destination, Change the Route. When an experiment dies, run a blameless review with four questions:
What was the problem?
What did we try?
What was the root cause?
What could we have done better?
Try this week: ask your team to name the output metric for the work in front of them. If they can’t, start there.
Keeping comprehension debt in check
From AI Shipped It. Can Anyone Explain It? Warning signs you’re carrying it:
Incidents take longer to diagnose, even when the fix is small.
The answer to “how does this work?” is “let me ask the agent.”
People re-prompt to change code instead of reading it first.
One person, or nobody, can walk through a critical flow from memory.
New people can’t get up to speed from the docs.
Before the work starts: place it on the governance grid, decide how much understanding it needs, and name the person who will be able to explain it once it ships.
While the agents work: ask the agent to explain its choices and where it’s least sure, and read before you re-prompt.
Before you call it done: write a plain-language explanation a person can defend, and ask whether someone on call could understand it at 2 a.m. from what’s written down.
Every sprint: track time to diagnose next to velocity, and walk the team through one agent-built area.
Keeping specs true when agents build from them
From our issue on specs. Before the agent builds:
Every document it will read has a clear status and an owner.
A person, not an agent, approved it.
The process fits the risk. Small fix, small spec.
When something changes: change through a proposal, not an edit in place, and flag every downstream document that depends on what changed.
Before you call it done: every requirement traces to a spec and back, every skipped check is visible with a reason, and every number and constraint came from a person, not the agent.
Every month: prune your agent instruction files. If the agent could learn it by reading the code, cut it.
Part 2: Spec templates
These are the three core templates from Spec Factory, Mike’s open-source Claude Code plugin for spec-driven development. Each document answers one question:
PRD: why are we building this, and what outcome do users need?
Technical design (TDD): how will the system satisfy the PRD?
Feature spec: what exactly are we implementing, in a form a test can check?
The block at the top of each template (between the --- lines) is metadata the plugin uses to track approval and traceability. If you’re not using Spec Factory, keep the id and title and delete the rest. The sections underneath work with any tool, or with none.
PRD template
---
kind: prd
id: PRD-1
title: PRD - <product>
version: 1
approved: false # false or an ISO date; only scripts/sf_approve.py writes this
approved_by: null # written by sf_approve.py, never by the agent
upstream: [docs/factory/idea.md]
upstream_hashes: {} # written by sf_approve.py at approval, never by the agent
sources: [] # normalised inputs under context/
review: null # reviews/<name>-v1-findings.md once sf-review has run
cross_model_check: null # reviews/<name>-v1-codex.md, or "NOT_RUN: <reason>"
open_questions: [] # ids of rows still parked in docs/factory/questions.md
weight: standard # side | standard | enterprise
---
<!--
The chain: PRD → TDD → ADRs → Feature Specs → Tests → Code.
Traceability: PRD requirement → TDD/design constraint → feature REQ → test.
Division of labor — each artifact answers ONE question:
PRD Why are we building this, what outcome do users need?
(users, problems, goals, requirements, UX, scope, metrics)
TDD How will the system technically satisfy the PRD?
ADR Why this technical approach over the alternatives?
Spec What exactly are we implementing? (machine-verifiable)
Test How do we prove it works?
THE RULE: the PRD describes WHAT, never HOW. "The application will use
Redis" or "we will use an event-driven architecture" belongs in the
TDD/ADR — unless it is an externally imposed constraint, which goes in
§12. This keeps the PRD readable by product/business stakeholders while
the downstream artifacts carry the technical precision.
NFR example of the full chain (product-level here, technical downstream):
PRD NFR-1: 95% of searches return results within 2 seconds.
TDD Search uses the indexing service, target p95 1.5s for margin.
ADR Evaluated Postgres FTS, Elasticsearch, Algolia; chose ES because...
Spec REQ-12: results within the product's 2-second requirement.
Test TEST-42: 10,000 representative searches, verify p95 ≤ 2s.
Every section is addressed; genuine non-applicability gets one line WITH
the reason, never a bare N/A.
-->
# 1. Product Summary
One paragraph: what is being built, for whom, and why.
# 2. Problem Statement
What problem are we solving?
- **Current experience** — how users cope today.
- **User pain** — what it costs them, concretely.
- **Business/organizational impact** — what it costs us.
- **Why now** — what makes this the moment.
- **Evidence** — what supports the problem's reality (from the Idea Brief's
research and the interrogation; no invented numbers).
# 3. Goals
What outcomes must this product achieve? Measurable where possible.
- GOAL-1: ...
- GOAL-2: ...
# 4. Non-Goals
Explicitly what this product is NOT intended to solve — so scope cannot
drift back in through sympathy.
- NON-GOAL-1: ...
- NON-GOAL-2: ...
# 5. Users & Personas
For each primary persona:
- Who they are
- Their goals
- Their pain points
- Their relevant context (device, environment, frequency)
- Their permissions/role where relevant
# 6. UX & Experience Design
UX is not reducible to requirements: the relationships between screens,
flows, hierarchy, feedback, and recovery are decisions in their own right.
This section captures them at the product level; the deep design work
happens in `/sf-design-ux` and is linked back here.
## Primary User Journeys
The important end-to-end journeys — entry, steps, success exit, and what
the user experiences on failure. Flow diagrams where they materially
improve understanding:
```mermaid
flowchart LR
Start([user need]) --> Step1 --> Step2 --> Done([outcome])
```
## User Flows
## Information Architecture
## Interaction Requirements
## States & Edge Cases
Per critical flow: empty, loading, success, error, offline, partial
failure, permission denied, destructive actions, recovery.
## Accessibility
## Content & Terminology
## Design System
## Prototypes / Designs
Links to the wireframes and designs produced in `/sf-design-ux`.
## Usability Validation
How the experience will be validated with representative users. Design
intuition never becomes user evidence: only research/evaluation results
may establish claims about actual user behavior.
# 7. User Stories
Prioritized. Every P1 survived the scope knife-fight in the interrogation.
- P1: As a <user>, I want <capability>, so that <outcome>.
- P2: ...
# 8. Functional Requirements
Stable, testable product requirements. Each describes WHAT the product
must do, never HOW it is implemented. These ids are the root of the
traceability chain - TDD constraints link back here, and a feature spec
restates each REQ-n it serves, id and text verbatim, and never numbers one of
its own.
- REQ-1: WHEN <trigger> THE SYSTEM SHALL <response>.
- REQ-2: ...
## Requirement Index
One row per requirement, the single place scripts/sf_trace.py reads.
The tag is `MVP`, `LAUNCH`, or `LATER`; every `MVP` and `LAUNCH` row must map to a
spec unit, and the traceability gate fails on an orphan in either direction.
| ID | tag | EARS statement | source |
|---|---|---|---|
| REQ-1 | MVP | WHEN <trigger> THE SYSTEM SHALL <response>. | <context/ file, interview, or inference> |
# 9. Business Rules
Rules and policies that govern product behavior (pricing logic, limits,
eligibility, workflow policies).
- BR-1: ...
- BR-2: ...
# 10. Data & Privacy Requirements
Product-level only (the TDD owns the data architecture):
- What user/business data the product handles and why it needs each kind.
- What users would consider sensitive, and the product's promises about it.
- Consent, export, and deletion expectations users must be able to rely on.
- Retention the product commits to, in user terms.
- Applicable regimes (GDPR, CCPA, HIPAA, SOX, ...) where relevant.
# 11. Non-Functional Requirements
Product-level, user-observable, each measurable — performance, security,
accessibility, compliance, reliability as EXPERIENCED by users. Technical
implementation targets derive from these in the TDD.
- NFR-1: 95% of <action> completes within <n> seconds.
- NFR-2: The product is fully operable by keyboard and screen reader.
# 12. Externally Imposed Constraints
The ONLY place HOW-shaped statements belong in a PRD — and only when
imposed from outside: mandated platforms, required integrations,
contractual technologies, regulatory mechanisms, deadlines.
# 13. Success Metrics
Both directions:
- **Success** — the numbers that prove the goals are met.
- **Failure signals** — the observed numbers that would prove the product
is failing (a product with no failure signal cannot be evaluated).
# 14. Release Scope & Phasing
What v1 ships; the explicit v1 NOT-list (named features deliberately
deferred, so nobody "helpfully" builds them); later phases in one line
each.
# 15. Assumptions
Product-level beliefs not yet verified (demand, willingness to pay, usage
patterns), stated so a future reader can check them. A broken assumption
triggers a PRD review — and the riskiest ones should already carry a
validation plan from the Idea Brief.
# 16. Open Questions
Unresolved items consciously deferred, each with an owner or a revisit
trigger. Empty is acceptable only if it is honestly empty.Technical design (TDD) template
---
kind: tdd
id: TDD-1
title: Technical Design - <product>
version: 1
approved: false # false or an ISO date; only scripts/sf_approve.py writes this
approved_by: null # written by sf_approve.py, never by the agent
upstream: [docs/factory/prd.md]
upstream_hashes: {} # written by sf_approve.py at approval, never by the agent
sources: [] # normalised inputs under context/
review: null # reviews/<name>-v1-findings.md once sf-review has run
cross_model_check: null # reviews/<name>-v1-codex.md, or "NOT_RUN: <reason>"
open_questions: [] # ids of rows still parked in docs/factory/questions.md
weight: standard # side | standard | enterprise
---
<!--
Division of labor (each artifact has ONE responsibility):
TDD — WHAT the system is: architecture, boundaries, data/security
model, constraints. The technical baseline everything
depends on.
ADR — WHY each consequential decision was made: options, pros/
cons, diagrams, consequences. The TDD REFERENCES ADRs; it
never duplicates their analysis.
Feature Spec — WHAT a particular change must do: the machine-verifiable
implementation contract.
Tests — EVIDENCE the requirements are satisfied.
Chain: TDD → ADRs → Feature Specs → Tests → Implementation.
Every section below is addressed; genuine non-applicability gets one line
WITH the reason, never a bare N/A.
-->
# 1. Purpose & Scope
## Purpose
What system/product this TDD defines and what problem it solves.
## Scope
What is covered by this design.
## Out of Scope
What this design explicitly does not cover (so scope cannot drift back in).
# 2. Goals & Non-Goals
## Goals
What the design must achieve, testably stated.
## Non-Goals
What it deliberately does not attempt.
# 3. System Architecture
## Context Diagram
The system in its environment — users, external systems, trust boundaries:
```mermaid
flowchart LR
User --> System
System --> Ext[external dependency]
```
## Components & Boundaries
Per component: what it does, its interface, what it depends on — answerable
without reading its internals. Dependencies point one way; name any cycle
as debt with an owning ADR.
## Directory Ownership Map
Boundaries translate into directories, because the factory parallelizes by
disjoint file ownership. State explicitly which directories belong to which
component — feature specs draw their `owns:` globs from this map.
Slice vertically. Every feature must own at least one path under `tests/`
AND at least one path outside it, because the test writer may only write
`tests/**` and the builder is denied it — so a feature scoped to one layer
(all frontend, all E2E, all ops) leaves one of them nothing to write and is
refused at launch. `spec-factory plan` checks this; run it before approval.
| Component | Directories |
|---|---|
| <component> | `src/<x>/**`, `tests/<x>/**` |
# 4. Data Architecture
## Data Model
Core entities, their relationships, and the schema strategy (migrations
from day one).
## Data Flows
How data moves through the system and across its boundaries:
```mermaid
flowchart LR
In[source] --> Proc[processing] --> Store[(storage)] --> Out[consumer]
```
## Classification, Retention & Residency
What data is public/internal/confidential/restricted/PII; where it rests;
retention and deletion policy; residency requirements if applicable.
(Feature specs inherit these classifications in their `data:` front-matter.)
# 5. Security Architecture
## Threat Model
Who attacks this system, how, and what they get — including what a
malicious *authenticated* user can do. Abuse cases per critical flow.
## Trust Boundaries & Controls
Where trust changes (user↔service, service↔service, service↔third-party)
and the control at each boundary.
## AuthN / AuthZ
Identity model, session/token strategy, authorization model (RBAC/ABAC),
least privilege for service identities.
## Secrets, Keys & Encryption
Where secrets live, rotation policy, encryption in transit and at rest.
## Security Logging & Incident Posture
Audit trail, detection signals, and what happens when a component or its
data is compromised.
# 6. Reliability & Resilience
Failure modes per dependency (timeout, retry, circuit-break, user-visible
behavior), idempotency for anything retryable, back-pressure strategy,
recovery targets (what may be slow, what may be down, what may lose data
NEVER — from the PRD's failure tolerances).
# 7. Observability
What is logged, measured, and traced; the signals that page a human vs
inform a dashboard; how a 2am incident gets diagnosed with what exists.
# 8. Performance & Scalability
Honest load expectations at launch and at 10x, the measured or estimated
budgets (latency, throughput, storage), the wall you will hit and the
named escape route. Design for 10x, note the wall, stop.
# 9. Configuration & Environments
Configuration strategy (files/env/flags), the environments that exist
(dev/CI/prod), what differs between them, and how secrets reach each.
# 10. Dependencies & Compatibility
External services, libraries, and platforms with version/pinning strategy;
compatibility commitments (API versioning, supported clients/OS versions);
build-vs-buy outcomes (the reasoning lives in ADRs).
# 11. Assumptions
What this design believes true but has not verified — stated so a future
reader can check whether they still hold. A broken assumption triggers an
ADR review, not a silent design drift.
# 12. Architectural Constraints
The binding rules implementations must follow, stated as actionable
sentences ("all cross-service events go through the bus per ADR-0042").
Feature specs restate the relevant ones in their Implementation
Constraints; this section is the authoritative list.
# 13. Test Strategy & Traceability
The unit / integration / E2E-on-virtual-device split, what runs in which
gate, per-surface E2E costs accepted up front (Playwright web, Android
emulators, iOS Simulator on macOS runners), coverage expectations — and
how requirements trace: PRD (or brief) REQ-n → the FEAT specs restating
it verbatim → tests, with the harness enforcing the REQ→test link
mechanically.
# 14. Feature-Spec Contract
How this design decomposes into feature specs: the planned FEAT list with
one-line scope each, their dependency order (`depends_on:`), and which can
run in parallel (disjoint ownership per the map in §3). Each spec inherits
this TDD's constraints and its governing ADRs.
| FEAT | Scope | Depends on | Governing ADRs |
|---|---|---|---|
| FEAT-001 | ... | — | ADR-0001 |
The block below is the machine-readable form of that table, and the one
`spec-factory plan` reads. The table above is for humans; this is the source
both it and the §3 map should agree with. `owns` is what the spec's `owns:`
will be; `requirements` and `nfrs` are rough counts that size agent budgets
(60s per requirement-or-NFR, or the role's floor, whichever is larger); and
`security_sensitive` marks the features that will carry SEC requirements or
PII, which gain two extra review phases.
Two features may share a path only if a `depends_on` edge serializes them —
disjointness is enforced against *live* runs, so chained features are
disjoint in time.
```yaml
plan:
- id: FEAT-001
owns: ["src/<x>/**", "tests/<x>/**"]
depends_on: []
adrs: [ADR-0001]
requirements: 12
nfrs: 2
security_sensitive: false
```
`spec-factory plan` also prices the plan from this block: phases per run,
agent wall-clock ceilings, the serial total, and the dependency floor that
no amount of parallelism beats. Those are ceilings the harness enforces
rather than forecasts, and reading them is part of approving a design — a
plan whose cost nobody looked at is a plan nobody sized.
It reports dollars too, but only once this project has history: spend per
requirement is measured from completed runs (failures included, because you
paid for those), and until there is anything to measure it says so instead
of inventing a number.
# 15. ADR Index
Every consequential decision, one line each — the reasoning lives in the
ADR, not here:
| ADR | Decision | Status |
|---|---|---|
| ADR-0001 | <one-line decision> | Accepted |
# 16. Open Questions
Unresolved items consciously deferred, each with an owner or a revisit
trigger. Empty is acceptable only if it is honestly empty.Feature spec template
---
kind: spec
id: FEAT-NNN
title: <one-line feature name>
version: 1
approved: false # false or an ISO date; only scripts/sf_approve.py writes this
approved_by: null # written by sf_approve.py, never by the agent
upstream: [docs/factory/prd.md, docs/factory/tdd.md]
upstream_hashes: {} # written by sf_approve.py at approval, never by the agent
sources: [] # normalised inputs under context/
review: null # reviews/<name>-v1-findings.md once sf-review has run
cross_model_check: null # reviews/<name>-v1-codex.md, or "NOT_RUN: <reason>"
open_questions: [] # ids of rows still parked in docs/factory/questions.md
weight: standard # side | standard | enterprise
adrs: [] # ADR-NNNN ids whose constraints this spec inherits
owns: ["src/<area>/**", "tests/<area>/**"] # at least one; test paths included
reads: [] # paths the implementation may read but not modify
depends_on: [] # FEAT-NNN ids that must be merged first
surface: none # ui | api | none
data:
classification: internal # public | internal | confidential | restricted
pii: false
secrets: false
requirements: # at least one; upstream REQ-n only, never numbered here
- id: REQ-1 # an id the requirement index (PRD, or brief at side weight) already carries
text: <that requirement's statement, copied verbatim from the index>
evidence: [unit]
security:
authentication: null
authorization: null
security_requirements: [] # each entry written as "SEC-n: <testable statement>"
non_functional_requirements: []
risk: standard # low | standard | high
---
# Design Notes
Written for the developer who builds this feature. State the contract as it
is now: why an earlier version read differently lives in the change proposal
and the findings, never here. Say each rule in words and cite its id after it,
"moving work never moves the clock (REQ-9)", not "per REQ-9".
## Summary
A few plain sentences, at most 200 words, a developer reads before anything
else: what the feature does and for whom, what it deliberately does not do,
and the one behaviour a builder is most likely to get wrong. No ids needed.
## Context
Why this feature is needed and the problem it solves. Link the PRD ids it
serves.
## Scope
### In Scope
- ...
### Out of Scope
- What an eager builder might helpfully add — named and excluded.
## Assumptions
Implementation-relevant assumptions only (the owning ADRs hold the full
architectural assumptions — do not duplicate them; identify the ones this
implementation leans on):
- The existing authentication service remains available.
- The API contract defined by ADR-XXX remains unchanged.
If an assumption proves wrong during the build, that is a spec deviation:
the run parks, and the fix is an ADR review + spec amendment — never a
silent workaround in code.
## Design
How the feature will work, within the constraints inherited from its ADRs.
### Architecture
```mermaid
flowchart LR
A[caller] --> B[this feature]
B --> C[(storage)]
```
### Data Flow
Flow diagram where applicable.
## Behavior
Important workflows, state transitions, edge cases, error handling, and
expected behavior - precise enough that a test writer who never saw the
design conversation can pin every branch.
One ### subsection per operation or flow, each saying when it happens, what
the system does, what the caller sees on success, and each failure with what
is returned. Where there are several failures or states, a table. Short
paragraphs: one rule each.
### <Operation or flow>
| Situation | What the system does | What the caller sees |
|---|---|---|
| <success> | ... | ... |
| <failure> | ... | ... |
## Examples
The handful of concrete input-to-output examples the downstream tests reproduce
verbatim, so an implementation cannot satisfy this spec by paraphrasing it.
Each is a named situation, exact inputs, and the exact expected output, ending
with the source its expected value comes from: a requirement, a design
section, an ADR, or an interview answer, quoted inside the source because
reviewers never see the transcript. An expected value no source fixes is a
question for the interview, never a guess.
- FEAT-NNN-E1: <situation>, <exact inputs> -> <exact expected output> (source: REQ-n)
## Acceptance Criteria
Observable evidence the feature is DONE (distinct from requirements, which
state what must be true, and tests, which prove it):
- Given <situation>, the system <observable outcome>.
On a `surface: ui` spec, "observable" means USER-observable (quality floor
QF-6): "the user sees the second location's conditions",
never "`selectedLocation.value` is the second location". A criterion no
user could verify by looking at the screen is a spec defect.
## Test Strategy
How each requirement will be verified. TEST ids become real test ids
(`path/test_x.py::test_name`) at build time; the red gate proves each one
fails before implementation and the traceability gate maps them back.
| Requirement | Test intent | Verification |
|---|---|---|
| REQ-1 | TEST-001: <inject X, verify Y> | Automated |
| REQ-2 | TEST-002: <...> | Automated |
| NFR-1 | TEST-003: <...> | Automated / Measured |
## Operational Considerations
Logging, monitoring, telemetry, configuration, deployment, rollback,
migration, and support considerations for this feature.
## Implementation Constraints
Technology, API, dependency, compatibility, or architectural constraints
the implementation must follow — including the specific constraints
inherited from each ADR listed in the front-matter, stated here as
actionable rules ("all cross-service events go through the bus per
ADR-042; no direct HTTP between services").Want the full workflow these templates come from? Spec Factory is open source and MIT licensed.
If you use any of this with your team, hit reply on any issue and tell us how it went. What worked, what you changed, and what didn’t fit. The best stories become future issues.
Mike and Rishi
The opinions expressed here are our own and do not represent any employer, past or present.