mandrel 1.94.0 → 2.1.0

package/.agents/skills/core/diagnose-friction/SKILL.md

@@ -14,21 +14,20 @@ allowed_tools:
 
 ## Policy Capsule
 
-- Invoke via the wrapping CLI `node .agents/scripts/diagnose-friction.js --task <id> --story <id> --epic <id> --cmd <command args...>`; this is the single supported entry point.
+- Invoke via the wrapping CLI `node .agents/scripts/diagnose-friction.js --story <id> [--epic <id>] --cmd <command args...>`; this is the single supported entry point.
 - Pass the wrapped command's stdout and stderr through **unchanged** — never reformat, redact, or buffer in a way that loses the original failure shape.
 - Never mutate the wrapped command's exit code. The Skill observes; the caller decides whether the failure is fatal.
 - Operate as **best-effort observation**: a write failure on the signals stream MUST NOT halt the runner. A missing signal is preferable to a stalled wave.
 - On non-zero exit append a `friction` NDJSON record (`kind`, `ts`, `category`, `detail`, `exitCode`) only through the signals writer helper — never open `signals.ndjson` directly.
-- Resolve Story / Epic context from `--story` and `--epic` first; fall back to parsing `parent: #<storyId>` + `Epic: #<epicId>` from the Task body when only `--task` is supplied.
-- Do **not** post GitHub comments from this Skill. Friction is local NDJSON in v5; the structured-comment surface belongs to `analyze-execution`.
-- Categorize failures deterministically (rebase abort, test-suite name, lint category, etc.) so the downstream analyzer can attribute friction without re-running the command.
+- Resolve Story context from `--story` (and `--epic` when a run id applies); there is no body-parsing fallback — pass the flags explicitly.
+- Do **not** post GitHub comments from this Skill. Friction is local NDJSON: the retro is what aggregates the stream and routes recurring friction into proposals (Story #4545 deleted `analyze-execution`, the perf-summary comment surface).
+- Categorize failures deterministically (rebase abort, test-suite name, lint category, etc.) so the retro can attribute friction without re-running the command.
 
 ## Role
 
 Diagnostic interceptor. Captures the failure shape of a wrapped command
-and persists it as a structured signal so `analyze-execution` can
-attribute friction back to the Story / Epic without re-running the
-command.
+and persists it as a structured signal so the retro can attribute friction
+back to the Story without re-running the command.
 
 ## When to use
 
@@ -41,26 +40,24 @@ that want to dispatch via the Skill tool rather than spawn the CLI.
 ## Inputs
 
 - `--cmd <command args...>` — the command to invoke and observe.
-- `--story <id>` / `--epic <id>` (optional) — when both can be
-  resolved, the Skill appends a `friction` signal to
-  `<tempRoot>/epic-<eid>/story-<sid>/signals.ndjson` on non-zero exit.
-- `--task <id>` (optional) — used as a fallback so the body parser can
-  recover `parent: #<storyId>` + `Epic: #<epicId>` when neither flag
-  was supplied.
+- `--story <id>` / `--epic <id>` (optional) — when resolved, the Skill
+  appends a `friction` signal to
+  `temp/run-<eid>/stories/story-<sid>/signals.ndjson` on non-zero exit
+  (standalone Stories: `temp/standalone/stories/story-<sid>/`).
 
 ## Outputs
 
 - The wrapped command's stdout / stderr is passed through unchanged.
 - On non-zero exit: a `friction` NDJSON record (kind, ts, category,
   detail, exitCode) is appended via the signals writer.
-- No GitHub comments are posted — friction is a local NDJSON signal in
-  v5. The analyzer (`analyze-execution`) reads the stream out-of-band.
+- No GitHub comments are posted — friction is a local NDJSON signal. The
+  retro reads the stream out-of-band.
 
 ## Procedure
 
 ```bash
 node .agents/scripts/diagnose-friction.js \
-  --task <id> --story <id> --epic <id> \
+  --story <id> [--epic <id>] \
   --cmd <command args...>
 ```
 
@@ -71,8 +68,7 @@ signal is preferable to a halted runner.
 ## Constraints
 
 - Do **not** post GitHub comments from this Skill. Friction is local
-  NDJSON in v5; the comment surface is reserved for
-  `analyze-execution`'s structured rollups.
+  NDJSON; the retro owns the aggregate surface.
 - Do **not** mutate the wrapped command's exit code. The Skill's job
   is observation; the caller decides whether the failure is fatal.
 - Do **not** open `signals.ndjson` directly — use the signals writer

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

@@ -12,406 +12,34 @@ description:
 
 - Document the **why**, not the what. Capture context, constraints, alternatives considered, and trade-offs — code already shows what was built.
 - Write an ADR for any decision that would be expensive to reverse (framework choice, data model, auth strategy, API architecture, hosting platform).
-- Mandrel ships **two first-class decisions-log layouts** — pick one at onboarding (see [Decisions-log layouts](#decisions-log-layouts)): the **single-file dated-entry** `docs/decisions.md` (default; best for small projects) or the **index + `docs/decisions/` directory** (MADR-style, one file per ADR; best once the log outgrows a single file). Either way, the canonical ADR sections are **Status, Date, Deciders, Context, Decision, (Alternatives Considered), Consequences**.
+- Mandrel ships **two first-class decisions-log layouts** — pick one at onboarding (see [Decisions-log layouts](reference.md#decisions-log-layouts)): the **single-file dated-entry** `docs/decisions.md` (default; best for small projects) or the **index + `docs/decisions/` directory** (MADR-style, one file per ADR; best once the log outgrows a single file). Either way, the canonical ADR sections are **Status, Date, Deciders, Context, Decision, (Alternatives Considered), Consequences**.
 - Mark an ADR's status as `Accepted`, `Superseded by ADR-XXX`, or `Deprecated`. Never silently delete an ADR — supersede it.
 - Do **not** document obvious code; do **not** restate what the code already says. Stale or redundant docs are worse than no docs.
 - Comments explain **non-obvious intent** (the why). If a comment describes what the code does, refactor the code instead.
 - Keep user-facing docs (README, API docs, changelog) updated as part of the change — out-of-date docs are bugs.
-- Pair every public API change with a changelog entry that links the relevant Story/Epic and any superseding ADR.
+- Pair every public API change with a changelog entry that links the relevant Story and any superseding ADR.
 - When you find yourself explaining the same thing repeatedly in chat, write it down — the explanation belongs in the project docs or an ADR.
 
-## 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
-
-Mandrel ships **two supported layouts** for the decisions log. Both keep the
-mandatory-read file named `docs/decisions.md` (the `project.docsContextFiles`
-default), so `config-resolver.js` and every `.agents/` reference resolve the
-same regardless of which you pick — only the **shape** differs. Choose one at
-onboarding:
-
-| Layout                              | Shape                                                                 | Template(s)                                                                                                | When to use                                                                       |
-| ----------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| **Single-file dated entries** (default) | One `decisions.md` of append-only `## YYYY-MM-DD — title` entries     | [`templates/docs/decisions.md`](../../../templates/docs/decisions.md)                                      | Small projects; a handful of decisions; you want everything in one scannable file. |
-| **Index + `decisions/` directory**  | `decisions.md` is a one-row-per-ADR **index**; each ADR is `decisions/NNNN-*.md` | [`templates/docs/decisions.index.md`](../../../templates/docs/decisions.index.md) + [`templates/docs/decisions/_template.md`](../../../templates/docs/decisions/_template.md) | The log has outgrown a single file (dozens of ADRs); you want per-decision history and `git blame` per ADR. |
-
-To adopt the directory layout, replace `decisions.md` with the index variant,
-create a `decisions/` directory beside it, and scaffold each ADR from
-`decisions/_template.md` using zero-padded sequential numbering
-(`0001-*.md`, `0002-*.md`, …).
-
-> **Loading model (resolved design question).** The decisions **index** is the
-> only artifact loaded into mandatory task context — individual ADR bodies
-> under `decisions/` are **lazy / link-followed**, not auto-loaded. This is
-> **index-only by default**: auto-loading every ADR body into each task's
-> context would reintroduce exactly the bloat the split exists to remove.
-> `project.docsContextFiles` entries are plain filenames resolved against the
-> docs root (no glob expansion in the loader), so the index ships as a normal
-> mandatory-read with no loader change. A project that genuinely wants the full
-> ADR set in mandatory context can add explicit per-file entries (or a
-> `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
-
-```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)
-```
-
-## 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.
-
-### 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.
-
-### 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.
-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`,
-   `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.
-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.
-
-### When to prune
-
-- A changelog, decision log, or runbook has grown long enough that the live
-  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.
-
-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
+## Long-form reference — read on demand
+
+The capsule above is the contract and the whole always-read surface of this
+skill. The long-form material behind it — patterns, worked examples,
+checklists, and rationalizations — lives in the on-demand sibling
+[`reference.md`](reference.md), matching the split the always-on rules already
+use ([`rules/git-conventions.md`](../../../rules/git-conventions.md) ⇄
+[`git-conventions-reference.md`](../../../rules/git-conventions-reference.md)).
+Activating this skill costs the capsule; open a section below only when the
+task actually engages it.
+
+- [Overview](reference.md#overview)
+- [When to Use](reference.md#when-to-use)
+- [Architecture Decision Records (ADRs)](reference.md#architecture-decision-records-adrs)
+- [Inline Documentation](reference.md#inline-documentation)
+- [API Documentation](reference.md#api-documentation)
+- [README Structure](reference.md#readme-structure)
+- [Changelog Maintenance](reference.md#changelog-maintenance)
+- [Pruning & Archiving](reference.md#pruning-archiving)
+- [Documentation for Agents](reference.md#documentation-for-agents)
+- [Common Rationalizations](reference.md#common-rationalizations)
+- [Red Flags](reference.md#red-flags)
+- [Verification](reference.md#verification)