Documentation and ADRs
Overview
Document decisions, not just code. The most valuable documentation captures the why — the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered. This context is essential for future humans and agents working in the codebase.
When to Use
- Making a significant architectural decision
- Choosing between competing approaches
- Adding or changing a public API
- Shipping a feature that changes user-facing behavior
- Onboarding new team members (or agents) to the project
- When you find yourself explaining the same thing repeatedly
- Someone asks "how did you do this?" or "why did you do it this way?" about an already-built feature, and the answer is worth keeping somewhere findable — see Feature Explanation below
When NOT to use: Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.
Complexity Found While Documenting: Offer to Simplify First
This applies across every artifact this skill produces — an ADR's Consequences, a Feature Explanation's Technical Explanation, a Data Flow Trace's hop — whenever the real code being read to document it turns out to be the kind of messy that makes it hard to write a clean, honest explanation of. Documentation written straight over genuinely tangled code either inherits the tangle (an explanation as hard to follow as the code was) or quietly smooths over it (an explanation that undersells how convoluted the real implementation actually is) — neither is a reason to write around the problem instead of naming it.
Recognizing it: use the same concrete signals code-simplification scans for, not a subjective "this feels complicated" — deep nesting (3+ levels), long functions (50+ lines), nested ternaries, duplicated logic across the files being documented, or naming unclear enough to make the mechanism genuinely hard to state plainly. A function that's merely long but linear, or code that's just unfamiliar, doesn't count — that's complexity the explanation can still describe cleanly. This is for code that's hard to accurately describe because it's tangled, not because it's new to you.
What to do when found: pause and ask via AskUserQuestion before writing that part of the entry:
- Simplify this part first, then document it — invoke
code-simplificationscoped to just the flagged file(s)/section, review its Simplification Report, then write the entry against the result - Continue documenting it as-is — write the entry describing the real code as it stands today, complexity included
If more than one spot is flagged while writing a single entry or trace, bundle them into one cumulative question listing each flagged location rather than asking once per spot — the same pattern incremental-implementation already uses for its post-review fix-scope choice: simplify all of them / continue as-is / pick which of these to simplify.
If the user picks simplify, the entry documents the code after simplification, not the version that triggered the question — note in the entry that it was simplified first where that context matters (an ADR's Consequences, or a Technical Explanation mentioning the mechanism was cleaned up while being recorded). If the user picks continue, document the real code honestly; don't quietly smooth a Technical Explanation or trace hop into sounding simpler than the code actually is.
This is always a question to the user, never a decision made silently — simplifying code is an edit to the project, not a documentation action, and this skill doesn't make that call on its own.
Architecture Decision Records (ADRs)
ADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.
When to Write an ADR
- Choosing a framework, library, or major dependency
- Designing a data model or database schema
- Selecting an authentication strategy
- Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
- Choosing between build tools, hosting platforms, or infrastructure
- Any decision that would be expensive to reverse
Match the Existing Convention First
Before applying the default template below, check whether this project already has an ADR convention — existing ADRs anywhere in the repo, project instructions that name one, or ADR-related tooling (e.g. an .adr-dir file, an adr-tools setup, a MADR layout). An established convention overrides the default in every respect: match its location and file format (Markdown vs. reStructuredText, a Documentation/Decisions/*.rst layout, etc.), continue its existing numbering and filename pattern rather than restarting at 001 or inventing a second scheme, and reuse its section headings rather than imposing this skill's own. If the evidence conflicts — two different numbering schemes already in use, say — surface the conflict to the user rather than silently picking one. Only write to the external-output default below when no existing convention can be established.
ADR Template
Store ADRs in decisions/ under the project's external output location (see references/external-output-paths.md) — outside the project's own repo, never a path git in this project tracks or ignores, with sequential numbering — unless an existing project convention says otherwise (see above):
# ADR-001: Use PostgreSQL for primary database
## Status
Proposed | Accepted | Superseded by ADR-XXX | Deprecated
## Date
2025-01-15
## Context
We need a primary database for the task management application. Key requirements:
- Relational data model (users, tasks, teams with relationships)
- ACID transactions for task state changes
- Support for full-text search on task content
- Managed hosting available (for small team, limited ops capacity)
## Decision
Use PostgreSQL with Prisma ORM.
## Alternatives Considered
### MongoDB
- Pros: Flexible schema, easy to start with
- Cons: Our data is inherently relational; would need to manage relationships manually
- Rejected: Relational data in a document store leads to complex joins or data duplication
### SQLite
- Pros: Zero configuration, embedded, fast for reads
- Cons: Limited concurrent write support, no managed hosting for production
- Rejected: Not suitable for multi-user web application in production
### MySQL
- Pros: Mature, widely supported
- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
- Rejected: PostgreSQL is the better fit for our feature requirements
## Consequences
- Prisma provides type-safe database access and migration management
- We can use PostgreSQL's full-text search instead of adding Elasticsearch
- Team needs PostgreSQL knowledge (standard skill, low risk)
- Hosting on managed service (Supabase, Neon, or RDS)
Ground Structural Decisions in references/coding-patterns.md
When the decision being recorded has implications those patterns cover — a new external integration, a data model, an auth strategy, anything with a retry/permission/pricing decision buried in it — read references/coding-patterns.md before writing Decision/Consequences, and name the concrete implication (e.g. "the provider lives behind a PaymentGateway interface, not called directly from order logic") rather than leaving it implicit. Not every ADR needs this — a build-tool choice usually doesn't — but skipping it for one that clearly does leaves the ADR's Consequences section silent about a real architectural commitment.
Check references/library-reuse.md Before Recording a "Build It Ourselves" Decision
When the ADR's Decision is to hand-write something — date handling, validation, an HTTP layer, auth, a queue, any category references/library-reuse.md covers — read that reference first. It's language-agnostic: find the row for this project's actual language/framework (Node/TS, Python, C#/.NET, Go, and more), not a JS/TS default out of habit. If it names a proven library for this category in that ecosystem, the ADR's Alternatives Considered must include that library as an option and state why it was rejected (a real constraint — bundle size, licensing, an unusual requirement the library doesn't support) rather than the ADR silently never considering it. An ADR that reinvents a solved problem without this comparison reads as if the option was never known, not deliberately passed over.
Check references/code-review-checklist.md for the Decisions It Already Covers
Several ADR-worthy decisions have a known-good default shape that references/code-review-checklist.md already states, as architectural rules rather than review nits: crossing into another domain's data (module/domain boundaries, §3a), a schema or index change (migration discipline, §3b), two fields representing overlapping state (redundant-state/dual-write consistency, §4), and a third-party integration's permission scope (least privilege, §5). When the ADR being recorded is one of these, read the relevant section before writing Decision/Consequences, and state the concrete shape explicitly (e.g. "cross-domain reads go through OrderReader, never the Order model directly" or "status is written only through applyOrderStatus, never set independently at each call site") — these decisions tend to get revisited expensively once a PR has already shipped the wrong shape, which is exactly what an ADR exists to prevent.
ADR Lifecycle
PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)
- Don't delete old ADRs. They capture historical context.
- When a decision changes, write a new ADR that references and supersedes the old one.
Inline Documentation
When to Comment
Comment the why, not the what:
// BAD: Restates the code
// Increment counter by 1
counter += 1;
// GOOD: Explains non-obvious intent
// Rate limit uses a sliding window — reset counter at window boundary,
// not on a fixed schedule, to prevent burst attacks at window edges
if (now - windowStart > WINDOW_SIZE_MS) {
counter = 0;
windowStart = now;
}
When NOT to Comment
// Don't comment self-explanatory code
function calculateTotal(items: CartItem[]): number {
return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}
// Don't leave TODO comments for things you should just do now
// TODO: add error handling ← Just add it
// Don't leave commented-out code
// const oldImplementation = () => { ... } ← Delete it, git has history
Document Known Gotchas
/**
* IMPORTANT: This function must be called before the first render.
* If called after hydration, it causes a flash of unstyled content
* because the theme context isn't available during SSR.
*
* See ADR-003 for the full design rationale.
*/
export function initializeTheme(theme: Theme): void {
// ...
}
API Documentation
For public APIs (REST, GraphQL, library interfaces):
Inline with Types (Preferred for TypeScript)
/**
* Creates a new task.
*
* @param input - Task creation data (title required, description optional)
* @returns The created task with server-generated ID and timestamps
* @throws {ValidationError} If title is empty or exceeds 200 characters
* @throws {AuthenticationError} If the user is not authenticated
*
* @example
* const task = await createTask({ title: 'Buy groceries' });
* console.log(task.id); // "task_abc123"
*/
export async function createTask(input: CreateTaskInput): Promise<Task> {
// ...
}
OpenAPI / Swagger for REST APIs
paths:
/api/tasks:
post:
summary: Create a task
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTaskInput'
responses:
'201':
description: Task created
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'422':
description: Validation error
README Structure
Every project should have a README that covers:
# Project Name
One-paragraph description of what this project does.
## Quick Start
1. Clone the repo
2. Install dependencies: `npm install`
3. Set up environment: `cp .env.example .env`
4. Run the dev server: `npm run dev`
## Commands
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm test` | Run tests |
| `npm run build` | Production build |
| `npm run lint` | Run linter |
## Architecture
Brief overview of the project structure and key design decisions.
Link to ADRs for details.
## Contributing
How to contribute, coding standards, PR process.
Changelog Maintenance
For shipped features:
# Changelog
## [1.2.0] - 2025-01-20
### Added
- Task sharing: users can share tasks with team members (#123)
- Email notifications for task assignments (#124)
### Fixed
- Duplicate tasks appearing when rapidly clicking create button (#125)
### Changed
- Task list now loads 50 items per page (was 20) for better UX (#126)
Feature Explanation
A different kind of documentation from an ADR or a README: a short, three-tier lookup entry for "how does this work" questions that come up after a feature ships. "How did you do this?" has more than one honest answer depending on who's asking and how deep they want to go — a plain-English answer for a non-technical asker, a prose walkthrough of the actual mechanism for someone who wants the real flow without reading code, and a precise technical answer naming the real implementation for someone who's going to go look at it — and all three should exist in one place so they don't have to be reconstructed from memory every time someone asks again.
For a feature whose full reach needs to be traceable — not just "roughly how it works" but exactly which files and calls it touches, in order, especially through the API/backend layer — this capability also has a deeper, optional Data Flow Trace mode. See that section below; it's a separate, heavier artifact from the three-tier entry, not a fourth paragraph bolted onto it.
When This Capability Applies
- The user asks to document, explain, or "record" how a specific feature works (e.g. "write up a feature explanation for the analytics date-filter")
- The user wants the skill to find and document the codebase's own most complex/significant features, without naming one
- A conversation surfaces a "how did you do this?" / "why did you do it this way?" question about something already built, and the user wants the answer kept somewhere findable instead of only in chat history
NOT for a feature still being designed or built — this documents something that already exists and works, grounded in the real implementation, not a planned one (breakdown-feature-implementation/spec-driven-development own that stage).
Clarify the Scope First
If the request doesn't already make this unambiguous (a user naming a specific feature by name is unambiguous — skip straight to writing that one entry), ask via AskUserQuestion:
- Document one feature I'll point you to — the user names it, or describes it well enough to locate
- Find and document the top features yourself — scan the codebase for its most complex/significant pieces of logic and propose a shortlist (default 5, adjustable) before writing anything
- Generate data flow traces for the most relevant features yourself — a separate scan tuned for Data Flow Trace rather than the standard entry (see Finding the Top Features for a Data Flow Trace, below)
- Only ask this when genuinely unclear which is wanted — don't add a question to a request that already named a specific feature.
Clarify the Depth, for a Single Named Feature
A top-N scan for standard entries always produces standard three-tier entries — depth only applies when a specific feature is named (pointed-to, not scanned), since a full Data Flow Trace per feature is too heavy to default to across a whole shortlist built for the standard-entry scan. When a single feature is named, ask via AskUserQuestion (unless the request already said which, e.g. "trace the full data flow of X" or "just a quick explanation of X"):
- Standard entry — the three-tier Plain English / How It Works / Technical Explanation entry described below (recommended default for "explain this" / "how does this work" asks)
- Full data flow trace — a deeper, file:line-anchored trace of every file and call this feature touches end to end, especially the API/backend layer (see Data Flow Trace below) — for when the ask is really "what does this touch, all the way through" rather than "how does this work at a glance"
Both can exist for the same feature; writing a trace later for a feature that already has a standard entry just adds the trace and links it from that entry (see Data Flow Trace's save location below), it doesn't replace anything.
Finding the Top Features (Scan Mode Only)
When asked to find features rather than being pointed at one, look for real complexity, not line count or file size: non-trivial business logic, a calculation or aggregation with several steps, a multi-step flow with branching, an integration with real edge cases — not boilerplate CRUD or a thin pass-through. Propose the shortlist (name + one-line reason each) and confirm it with the user via AskUserQuestion before writing any entries — don't silently commit to a list the user might not recognize as "the interesting parts," and don't write more than they asked for just because more candidates were found.
Finding the Top Features for a Data Flow Trace (Scan Mode)
This is a separate scan from the one above — it runs when the user wants traces generated for the project's most relevant features rather than being asked to name one, and it's tuned for a different kind of "interesting": not just complex business logic, but features whose code actually reaches far — crosses several files or modules, calls out to an API/backend layer, touches more than one service, or has a fan-out point where one call feeds more than one downstream consumer (the exact shape of thing that's easy to be caught unprepared explaining, which is the whole reason this mode exists). Boilerplate CRUD or a single-file feature, however complex its logic, is a worse trace candidate than a thinner feature that happens to hop through five files and an external call.
- Confirm the user wants this via
AskUserQuestionif it isn't already explicit in the request (e.g. "trace the top features" is explicit; "document the project" is not and should default to the standard-entry scan instead, asking only if genuinely ambiguous). - Scan for candidates against the reach-based criteria above and propose a shortlist of 5-7 (adjustable, same as the standard scan's default of 5) — name + one-line reason each, phrased around what the feature touches (e.g. "order checkout — API route, three services, and an external payment gateway").
- Confirm the shortlist with the user via
AskUserQuestionbefore writing anything — don't silently commit to it. - Once confirmed, write out the Data Flow Trace for each confirmed feature the same way a single named-feature trace is written (see Data Flow Trace below) — this scan's whole point is producing the traces, not just proposing which features would be worth tracing.
- After this batch is written, the user can ask for additional features to be traced on top of it at any time — treat that exactly like a newly named feature (check whether it already has a trace first, same as any other artifact this skill produces), not as reopening or redoing the shortlist.
Writing an Entry
Each entry is genuinely brief — 3-4 paragraphs total, not per section. This is a quick-reference lookup, not a design doc; if a feature needs more than that to explain, link out to its ADR or implementation plan rather than inflating the entry. Every claim is grounded in what's actually in the code — read the real implementation before writing a word, same rule as acquire-codebase-knowledge/story-mode; never guess at a mechanism that sounds plausible.
Three parts, always all three present, in this order:
- Plain English — what this lets someone actually do, in the vocabulary of whoever would ask "how does this work" without a technical background. No implementation detail here at all — purpose and capability only (e.g. "admins can see signup trends by week and filter them by which channel brought the signup in").
- How It Works — a prose walkthrough of the actual mechanism, one level down from Plain English but still not code: what gets checked, what gets computed or aggregated, what the backend receives and sends back, in the order it actually happens — but in engineering-process vocabulary, never raw code syntax, file paths, or function names (that's the next section's job). The test for whether something belongs here instead of Plain English or Technical Explanation: could a non-engineer follow the flow being described, even if some of the words are unfamiliar, without needing to know what a file or function actually is? E.g. "when the dashboard loads, it sends the selected date range to the backend, which pulls every signup in that range, groups them by week and by which channel brought the signup in, and sends back a count per week per channel for the chart to render." This is the layer that's usually missing — don't skip straight from capability to implementation detail.
- Technical Explanation — concretely how it's built, naming the real files, functions, queries, or mechanisms involved — specific enough that the reader could go find the code from the explanation alone (e.g. "
AnalyticsReader.getSignupTrends()runs an aggregation pipeline that groups by week with a$dateTruncstage and joinsUtmSourcefor channel attribution; the result is cached 5 minutes viaredisCache.wrap"). Generic restatement of the How It Works paragraph in more technical-sounding words is not a technical explanation — name the actual mechanism.
Data Flow Trace
The gap this closes: a "how does this work" entry can be honest and still leave someone unable to answer "wait, what else does this touch?" when a reviewer or teammate asks — because a feature whose code visibly calls through several layers of indirection can be quietly wired into something unrelated (a payments flow that also happens to feed an analytics pipeline) without that ever surfacing in a plain-English or even a How-It-Works-level answer. This mode exists specifically to make that reachable: trace the feature's actual path through the code, hop by hop, with file:line for each one, so nothing it touches is a surprise later.
Register: this is "not fully technical, but still technical" — every hop shows the actual code it's talking about, not a prose paraphrase standing in for it. Each hop is the real snippet (the exact lines from that file:line, trimmed to the relevant call/logic, in a fenced code block with the right language) followed by a short paragraph underneath explaining what it does and what it hands off next. The code block is what the reader checks against the real file; the paragraph underneath is what makes the code block's purpose legible without them having to work it out themselves. Neither replaces the other — a code block with no explanation is as incomplete as the prose-only version this mode replaced.
When to Use This Mode
- The user explicitly asks to trace a feature's data flow, "what does X call," "where does this data come from/go to," or wants the full path through the API/backend layer for a named feature
- Preparing to explain a feature in a review or demo where "what else does this touch" is a predictable question — tracing it in advance, once, beats being caught unprepared by it
- A feature's implementation visibly fans out to more than one consumer (e.g. a write that also triggers an event, a queue, or a second system) and that fan-out itself is the thing worth documenting clearly
How to Trace It
- Find the entry point. Where the feature's flow actually begins — a UI action, an API route, a scheduled job, an event handler. State it with file:line.
- Follow every hop forward, in the order execution actually takes it. For each hop, capture: the exact code at that file:line (trimmed to the relevant lines — the call, the check, the transform — not the whole surrounding function unless the whole thing is the relevant part), and a short explanation underneath it covering what it does and exactly what it passes to the next hop (the shape of the request/data, not just "data"). Don't skip a hop because it "just forwards" — a thin pass-through is still a hop the next reader needs to find on their own otherwise.
- Treat the API/backend layer as the layer to be most thorough about, per this mode's main purpose: for every network or service call, name the endpoint or method, what it sends, what it gets back, and what happens to the response.
- Flag every fan-out explicitly. The moment a single call's result is consumed by more than one downstream path — a webhook also logged to analytics, a save that also invalidates a cache and enqueues a job — call it out as its own numbered branch, not folded silently into the main line. This is the exact gap a trace exists to close: a feature that looks single-purpose from the entry point but quietly feeds something else further in.
- Note where it terminates — a response returned, a row persisted, a job enqueued, an event published — and don't follow a branch past the boundary of what this feature actually owns (e.g. trace that payment confirmation triggers an analytics event; don't then also trace everything the analytics system does with it unless that's the feature being traced).
- Ground every hop in code actually read, the same rule as the rest of this capability — never infer a call exists because the naming suggests it.
- Draw the small diagram (see Output Shape below) once the hops and fan-outs are known — it's easier to lay out after the trace is settled than to draw it first and reconcile the two.
Output Shape
Lead with a small diagram, then the numbered trace underneath it — the diagram is a map to orient on, the numbered steps are where the actual file:line detail and reasoning live. Never the diagram alone: a box can show that a call happens, not what it validates, what it fans out to, or why a branch matters.
The diagram: plain Markdown ASCII art in a fenced code block — boxes and -->/|/+ arrows, no Mermaid or any other diagramming syntax that needs a renderer to be readable. It has to read correctly as plain text in any Markdown viewer, including one with no diagram-rendering support at all. Keep it small: one box per hop, a short label — file:line plus a 2-4 word action, not the full sentence from the numbered step below it. Show the fan-out point as a visible branch (two arrows leaving one box, or a side branch offset from the main column) rather than a box indistinguishable from the main line. This is meant to stay small — past roughly 8-10 boxes for one trace, it's no longer "small," which usually means the trace itself is covering more than one feature's worth of flow and should be split.
The numbered trace: one hop per entry, and each hop is a code block, not a paragraph standing in for one — the exact lines from that file:line (trimmed to the relevant call/check/transform, with the surrounding function elided if it isn't relevant), labeled with the file:line, followed immediately by a short paragraph underneath explaining what it does and exactly what it hands to the next hop. No hop skips the code block and goes straight to prose — the paragraph supplements the snippet, it doesn't replace it.
## Data Flow Trace: Offline Credit Redemption — 2026-03-04
Entry point: `POST /api/credits/redeem`, handled at `routes/credits.ts:51`.
```
[credits.ts:51] [credits.ts:22] [ledger.ts:88]
receive + --> check code --> write ledger
validate auth unexpired/unused entry (tx)
|
+-----------------+-----------------+
| |
v v
[ledger.ts:101] [credits.ts:58]
emit credit.redeemed respond 200 + balance
|
v
[analytics/listeners.ts:14]
forward to analytics pipeline
```
### 1. `routes/credits.ts:51`
```typescript
router.post('/api/credits/redeem', requireAuth, async (req, res) => {
const { userId, creditCode } = req.body;
const result = await redeemCredit(userId, creditCode);
```
Receives `{ userId, creditCode }` after `requireAuth` has already run, then calls `redeemCredit()` at `services/credits.ts:22`.
### 2. `services/credits.ts:22`
```typescript
export async function redeemCredit(userId: string, code: string) {
const creditCode = await CreditCode.findUnexpiredUnused(code);
if (!creditCode) throw new InvalidCodeError(code);
return ledger.applyCredit(userId, creditCode);
```
Validates the code is unexpired and unused (`CreditCode` row lookup), then calls `ledger.applyCredit()` at `services/ledger.ts:88`.
### 3. `services/ledger.ts:88`
```typescript
export async function applyCredit(userId: string, creditCode: CreditCode) {
return db.transaction(async (tx) => {
const balance = await tx.ledger.insert({ userId, amount: creditCode.amount });
events.emit('credit.redeemed', { userId, amount: creditCode.amount });
return balance;
});
```
Writes the ledger entry inside a DB transaction, then fans out:
- **3a. `services/ledger.ts:101` — `events.emit('credit.redeemed', ...)`** — picked up by `analytics/listeners.ts:14`, which forwards it to the analytics pipeline. **This is the fan-out**: redemption always produces an analytics event, independent of the response below.
- **3b.** returns the updated balance back up the call stack.
### 4. `routes/credits.ts:58`
```typescript
res.status(200).json({ balance: result.balance });
});
```
Receives the updated balance, responds `200 { balance }` to the client.
Terminates: HTTP response to the client (step 4), and an async analytics event already published by that point (step 3a) — the two don't block each other.
Saving It
A trace is its own file, separate from the three-tier running log, because the file:line granularity makes it too long to append inline without burying the log's own skimmability: feature-explanations/data-flow-traces/<feature-slug>.md in the project's external output location (see references/external-output-paths.md) — same external-root rule as everything else this skill produces, never inside the project's own repo. Link it from feature-explanations/feature-explanations.md's index with a row of its own (or an added column on that feature's existing row, if it already has a standard entry) so it's discoverable from the same place everything else is. A later re-trace of the same feature (code changed since) overwrites that feature's trace file — a trace describes the code as it is now, not a history of how it evolved, unlike the append-only three-tier log.
Save as One Running Document, Indexed at the Top
Append each entry to feature-explanations/feature-explanations.md in the project's external output location (see references/external-output-paths.md) — a single running document for the project, always appended to, never overwritten or replaced, the same convention code-review's review-findings/review-findings.md uses, including its own dedicated folder rather than a bare file at the project root. This file is never written inside the project's own repository, not even a gitignored path — resolve the actual external root first and write there directly. Not splitting into multiple files only stays easy to use if the single file stays easy to search as it grows across many sessions and days — so every entry does two things, not one: it's appended to the log, and it gets a row in a maintained index kept at the very top of the same file.
Create the file on the first entry with this shape, then keep the index current on every later entry:
# Feature Explanations
One-line purpose of this file, and how to use it: check the index below for
the feature you're asked about, then jump to its dated entry.
## Index
| Feature | Date | Summary | Data Flow Trace |
|---|---|---|---|
| [Signup trend chart](#signup-trend-chart-2026-03-04) | 2026-03-04 | Weekly signups by channel, admin analytics page | — |
| [Cohort retention filter](#cohort-retention-filter-2026-03-11) | 2026-03-11 | Filters retention table by signup cohort | [trace](data-flow-traces/cohort-retention-filter.md) |
---
## Signup Trend Chart — 2026-03-04
**Plain English:** <1 short paragraph>
**How It Works:** <1 short paragraph — the mechanism in prose, no code/file names>
**Technical Explanation:** <1-2 short paragraphs, naming real files/functions/queries>
---
## Cohort Retention Filter — 2026-03-11
**Plain English:** <1 short paragraph>
**How It Works:** <1 short paragraph — the mechanism in prose, no code/file names>
**Technical Explanation:** <1-2 short paragraphs, naming real files/functions/queries>
The index row's Summary column is a one-line plain-English gist (not the full paragraph) — enough to recognize the right entry without opening it. The Feature column links to that entry's own heading anchor, so finding it is one click once the right row is spotted. The Data Flow Trace column links to that feature's trace file when one exists, or stays — when it doesn't — a trace is optional per feature, not something every entry needs. Every new entry gets a new index row at the time it's written — an entry with no index row defeats the entire reason this file doesn't get split into one file per feature.
This is exactly what makes the later "which doc do I check" question trivial, even months and many sessions later: scan one short table instead of a search through chat history, the whole codebase, or (worse) a growing pile of entries with no way to tell what's in them without opening each one.
A later request to explain an additional feature — including one found after the initial top-N pass, or one that only came up because someone asked about it, on a completely different day — appends a new entry and a new index row to this same file; it never starts a second document for the same project, and it never appends an entry without also updating the index.
Documentation for Agents
Special consideration for AI agent context:
- CLAUDE.md / rules files — Document project conventions so agents follow them
- Spec files — Keep specs updated so agents build the right thing
- ADRs — Help agents understand why past decisions were made (prevents re-deciding)
- Inline gotchas — Prevent agents from falling into known traps
Prose Review
After the technical content is right, review the prose itself for the people who'll actually read it. Clearer wording must never change the decision or its limits — this is an editing pass, not a second chance to revise the content.
- Mark the details that must survive the edit: names, numbers and units, commands, paths, links, conditions, trade-offs, and uncertainty. Check each against the available code and decision context; flag anything you can't substantiate rather than smoothing over it.
- Replace stock introductions, promotional adjectives, and repeated summaries with the concrete information the reader actually needs. Don't replace an unsupported claim with an invented example or a stronger guarantee than the evidence supports — cut the fluff, don't upgrade the claim. Keep necessary technical repetition and the project's own established terminology.
- Compare the edited document against the original and its sources. Restore any qualifier or caveat that got lost in editing, verify command/code examples still work as documented, and state any unresolved factual question explicitly rather than polishing it away.
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "The code is self-documenting" | Code shows what. It doesn't show why, what alternatives were rejected, or what constraints apply. |
| "We'll write docs when the API stabilizes" | APIs stabilize faster when you document them. The doc is the first test of the design. |
| "Nobody reads docs" | Agents do. Future engineers do. Your 3-months-later self does. |
| "ADRs are overhead" | A 10-minute ADR prevents a 2-hour debate about the same decision six months later. |
| "Comments get outdated" | Comments on why are stable. Comments on what get outdated — that's why you only write the former. |
| "I'll just use the standard ADR template, it's simpler than checking for a convention" | If the project already has ADRs, a different location, numbering, or heading set, a second scheme fragments the record — check for an existing convention first and match it. |
| "A clarity pass is just wordsmithing, it can't break anything" | Dropping a caveat, a condition, or a number while "tightening" the prose changes what the document actually commits to — treat the prose-review pass as something that needs its own verification against the original. |
| "I'll write a full technical deep-dive for this feature explanation, more detail is more helpful" | The whole point is a 2-3 paragraph lookup entry, not a design doc — more detail here just makes the next person skim past the part they actually needed. Link out to an ADR/plan for anything that needs more. |
| "I'll describe the mechanism in the same plain-English terms, just with more jargon" | That's not a technical explanation — name the actual file, function, or query involved, specific enough that someone could go find the code from the sentence alone. |
| "I'll start a new feature-explanations file for this one, it's a different kind of feature" | One running feature-explanations/feature-explanations.md per project, same as review-findings/review-findings.md — a second file defeats the point of having one place to check. |
| "I'll just append the entry, the index can be rebuilt later if needed" | "Later" means scrolling a growing file to reconstruct what's already in it — update the index the same moment the entry is written, every time, not as a deferred cleanup task. |
| "The How It Works paragraph already covers the mechanism, that's close enough to a trace" | How It Works is deliberately prose with no file names — a trace is the opposite: file:line for every hop. Asked for a trace, write the trace; don't hand back the paragraph with technical words swapped in. |
| "I'll skip the depth question, a named feature obviously just wants the standard entry" | Not always — "explain this" and "trace what this touches" are different asks that happen to name the same feature. Ask via AskUserQuestion unless the request's own wording already answered it. |
| "This hop just forwards the call, I'll skip it in the trace" | A thin pass-through is still a hop the next reader has to find themselves if it's missing — list it, even briefly. |
| "I'll mention the fan-out in passing, no need to call it out separately" | The fan-out is usually the entire reason someone asked fo |
…(truncated)
