mandrel 2.7.0 → 2.8.0

package/.agents/skills/core/documentation-and-adrs/reference.md

@@ -1,46 +1,14 @@
 # Documentation and ADRs — Reference (on-demand)
 
 **Read this when** a task engages one of the sections below and the Policy
-Capsule in [`SKILL.md`](SKILL.md) does not settle it on its own. The capsule
-is the contract; this file is the reference material behind it. Nothing here
-relaxes a capsule MUST, and nothing here is required reading merely because
-the skill is active.
+Capsule in [`SKILL.md`](SKILL.md) does not settle it on its own. The capsule is
+the contract; this file is the reference material behind it. Generic ADR
+templates, inline-comment / README / changelog conventions, and JSDoc/OpenAPI
+snippets are frontier-known and are not reproduced here — this file keeps the
+project-specific contracts: the two decisions-log layouts and their loading
+model, and the prune/archive convention for living docs.
 
-## 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
-
-**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.
-
-## 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
-
-### Decisions-log layouts
+## Decisions-log layouts
 
 Mandrel ships **two supported layouts** for the decisions log. Both keep the
 mandatory-read file named `docs/decisions.md` (the `project.docsContextFiles`
@@ -70,281 +38,59 @@ create a `decisions/` directory beside it, and scaffold each ADR from
 > `decisions/*.md`-style entry if it maintains its own globbing) as a
 > deliberate opt-in, but that is the exception, not the default.
 
-### ADR Template
-
-In the **single-file** layout, append a short dated entry per the
-`templates/docs/decisions.md` format. In the **directory** layout, store ADRs
-in `docs/decisions/` with sequential numbering:
-
-```markdown
-# ADR-001: Use PostgreSQL for primary database
-
-## Status
-
-Accepted | Superseded by ADR-XXX | Deprecated
-
-## Date
-
-2025-01-15
-
-## Deciders
-
-The platform team (architect + two senior engineers).
-
-## 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)
-```
-
-### ADR Lifecycle
+### ADR lifecycle (why archiving is not for ADRs)
 
 ```text
 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_:
-
-```typescript
-// 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
-
-```typescript
-// 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
-
-```typescript
-/**
- * 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)
-
-```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
-
-```yaml
-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:
-
-```markdown
-# 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:
-
-```markdown
-# 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)
-```
+Don't delete old ADRs — they capture historical context. When a decision
+changes, write a new ADR that references and supersedes the old one. An ADR that
+no longer holds is **superseded in place**, keeping the numbered chain intact;
+it is not pruned by archiving (see below).
 
 ## Pruning & Archiving
 
-Living docs accrete history — dated changelog entries, closed decision-log
-rows, completed rollout checklists, resolved runbook incidents. Left
-unpruned, that verbatim history crowds out the live guidance a reader (human
-or agent) actually needs, and every task that loads the doc re-pays the cost.
-The fix is to **archive, don't delete**: relocate the cold history so the live
-doc stays lean while the record stays recoverable.
+Living docs accrete history — dated changelog entries, closed decision-log rows,
+completed rollout checklists, resolved runbook incidents. Left unpruned, that
+verbatim history crowds out the live guidance a reader (human or agent) actually
+needs, and every task that loads the doc re-pays the cost. The fix is to
+**archive, don't delete**: relocate the cold history so the live doc stays lean
+while the record stays recoverable.
 
 ### The archive-don't-delete rule
 
 **History is preserved by _moving_ it, never by deleting it.** Pruning a doc
 never destroys its past — the verbatim content is relocated to a dated archive
-file under version control, so the full record remains diffable and
-recoverable. Deleting history outright (even with "git has it") is the
-anti-pattern this convention exists to prevent: the archive is discoverable
-from the live doc, a buried git revision is not.
+file under version control, so the full record remains diffable and recoverable.
+Deleting history outright (even with "git has it") is the anti-pattern this
+convention exists to prevent: the archive is discoverable from the live doc, a
+buried git revision is not.
 
 ### How to prune a doc
 
 1. **Extract the still-live signal first — before you archive anything.**
    Gotchas, traps, and hard-won caveats buried in the history are the most
-   valuable lines in the doc. Lift them into the live doc's standing guidance
-   (a "Known gotchas" list, an inline warning, or an ADR) **before** the
-   history moves. Archiving first risks stranding a live trap in a cold file
-   nobody rereads.
+   valuable lines in the doc. Lift them into the live doc's standing guidance (a
+   "Known gotchas" list, an inline warning, or an ADR) **before** the history
+   moves. Archiving first risks stranding a live trap in a cold file nobody
+   rereads.
 2. **Move the verbatim history to a dated archive file.** Relocate the cold
-   content — untouched, word-for-word — to
-   `docs/archive/<name>-<YYYY-MM>.md`, where `<name>` is the source doc's base
-   name and `<YYYY-MM>` is the archive date (e.g. `docs/archive/changelog-2025-01.md`,
+   content — untouched, word-for-word — to `docs/archive/<name>-<YYYY-MM>.md`,
+   where `<name>` is the source doc's base name and `<YYYY-MM>` is the archive
+   date (e.g. `docs/archive/changelog-2025-01.md`,
    `docs/archive/decisions-2024-11.md`). The archive is an exact copy of what
    was live; do not summarize or rewrite it in the move.
-3. **Collapse completed checklists to a one-line summary.** A finished
-   checklist (a rollout runbook, a migration plan, a release gate) does not
-   need to keep every ticked box in the live doc. Replace it with a single
-   line recording the outcome and date — e.g.
-   `Auth-migration rollout — completed 2025-01-18, all 12 steps green` — and
-   let the archived copy carry the full detail.
+3. **Collapse completed checklists to a one-line summary.** A finished checklist
+   (a rollout runbook, a migration plan, a release gate) does not need to keep
+   every ticked box in the live doc. Replace it with a single line recording the
+   outcome and date — e.g. `Auth-migration rollout — completed 2025-01-18, all
+   12 steps green` — and let the archived copy carry the full detail.
 4. **Leave a one-line pointer behind.** Every archived doc leaves exactly one
    line in the live doc pointing at where its history went, so the record is
-   never orphaned — e.g.
-   `Older entries archived to docs/archive/changelog-2024.md`. The pointer is
-   what makes "moved, not deleted" true from the reader's vantage point.
+   never orphaned — e.g. `Older entries archived to
+   docs/archive/changelog-2024.md`. The pointer is what makes "moved, not
+   deleted" true from the reader's vantage point.
 
 ### When to prune
 
@@ -352,52 +98,10 @@ from the live doc, a buried git revision is not.
   entries are hard to find among the historical ones.
 - A checklist or rollout plan is fully complete and its step-by-step detail is
   now reference-only.
-- A doc reloaded into agent context on many tasks carries more cold history
-  than live guidance.
+- A doc reloaded into agent context on many tasks carries more cold history than
+  live guidance.
 
 Do **not** prune ADRs by archiving — an ADR that no longer holds is
-**superseded** in place (see [ADR Lifecycle](#adr-lifecycle)), keeping the
-numbered chain intact. Archiving is for the accreted history of living docs,
-not for the immutable decision record.
-
-## 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
-
-## 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. |
-
-## Red Flags
-
-- Architectural decisions with no written rationale
-- Public APIs with no documentation or types
-- README that doesn't explain how to run the project
-- Commented-out code instead of deletion
-- TODO comments that have been there for weeks
-- No ADRs in a project with significant architectural choices
-- Documentation that restates the code instead of explaining intent
-
-## Verification
-
-After documenting:
-
-- [ ] ADRs exist for all significant architectural decisions
-- [ ] README covers quick start, commands, and architecture overview
-- [ ] API functions have parameter and return type documentation
-- [ ] Known gotchas are documented inline where they matter
-- [ ] No commented-out code remains
-- [ ] Rules files (CLAUDE.md etc.) are current and accurate
+**superseded** in place (see [ADR lifecycle](#adr-lifecycle-why-archiving-is-not-for-adrs)),
+keeping the numbered chain intact. Archiving is for the accreted history of
+living docs, not for the immutable decision record.