fhorja.dev

Senior accessibility auditor mapping a UI surface (screen, flow, or component set) to WCAG 2.2 at a named conformance level (A, AA, AAA). Produces ACCESSIBILITY_AUDIT.md, a per-criterion conformance ledger that splits machine-checkable rows from a manual-review queue, with severity and concrete remediation per finding. Activates when a screen-spec or implemented UI surface has no WCAG conformance ledger, when DECISIONS.md or PROJECT_CHARTER.md names an accessibility target without a per-criterion audit, or when a delivery surface needs a conformance pass before sign-off. Do not use for a single foreground/background contrast pair (use color-contrast-architect, which owns 1.4.3/1.4.11), for a single component against its spec (use design-spec-review), or when the task has no user-facing UI surface.

Design an evaluation plan for a product AI feature (LLM- or model-backed output): measurable success criteria, a held-out labeled eval dataset shape, per-criterion grading (code-based first, then LLM-based for nuanced judgment), and a pass threshold, then persist as AI_EVAL_PLAN.md. Use when the task ships or changes a feature whose output is model-generated or non-deterministic (assistant reply, classification, extraction, summarization, ranking, agent action) and needs a repeatable dataset-backed eval rather than only example-based tests. Do not use when the feature has no model-backed output (use test-strategy for deterministic behavior), when judging Fhorja's own command outputs against a rubric (use verify-against-rubric), or when no active task folder exists. The code-graded tier composes with ADR-0048 (a passing deterministic gate is Layer-1 evidence); the LLM-graded tier is added signal, not a replacement.

Review an API contract (endpoints, request/response shapes, error codes, auth model) BEFORE implementation for naming consistency, versioning, pagination, idempotency, and alignment with existing endpoints. Distinct from review-hard (post-implementation risk) and repo-consistency-sweep (pattern matching on written code). Use when designing new endpoints or modifying existing API contracts. Do not use when the API is already implemented (use review-hard or repo-consistency-sweep instead).

Verify a built mobile or app runtime at runtime: run the app (device, emulator, or headless), read the captured runtime output (native logcat, iOS device log, or the Metro/JS console), classify any runtime errors against a per-stack taxonomy, and decide a PASS/FAIL runtime gate for the slice's acceptance behavior. The run's real output IS the Layer-1 runtime evidence (ADR-0048); a claimed-but-not-shown run is unverified. Capability-routed and MCP-agnostic about how the app is run; React Native/Expo (logcat plus Metro) is the first documented adapter. It verifies and routes fixes, it does not apply them. Use after an app slice is implemented to gate runtime behavior the static checks (typecheck, lint) cannot catch. Do not use to plan a screen (use implementation-plan), to write or fix code (use implement-approved-slice), to triage a failure into a fix size (use incident-triage), to verify a Godot scene (use godot-runtime-verify), or with no implemented app to run.

Persist the user's triage decisions (apply, decline, discuss) from a SWEEP snapshot into REVIEW_PREFERENCES.md so future sweeps suppress declined findings and track applied fixes. Use after the user has edited the triage values in a SWEEP snapshot file produced by repo-consistency-sweep. Do not use when no sweep snapshot exists or when the user has not yet set triage values.

Atomically lock IMPLEMENTATION_PLAN.md as the approved execution baseline and stamp TASK_STATE.md with the approval signal. Symmetric counterpart to approve-proposed but for the plan itself, not for arbitrary PROPOSED artifacts. Use when IMPLEMENTATION_PLAN.md has been produced (or revised via self-critique-and-revise) and the user authorizes execution to begin. Do not use when the plan is still draft, when implementation-plan returned NO_OP, when the plan contains [NEEDS CLARIFICATION:] markers, or when revisions are still pending review.

Atomically persist every file marked PROPOSED in the most recent prior assistant turn's `### Artifact changes` block. Single-command idiom that closes the two-step latency in ADR-0001's PROPOSED-by-default contract; the user reviews proposals in Ask/Plan mode, then runs this once to write all of them. Use when the prior assistant turn ended with a `### Artifact changes` block containing one or more files marked PROPOSED and you have read and accepted the inline content for each. Do not use when the prior turn had no `### Artifact changes` block, every artifact is APPLIED or SKIP, you have not yet read the proposed content, or you want to approve only a subset (run the original command in Agent mode for partial approval).

Orchestrator-workers variant of atom-audit. Dispatches N Haiku workers (3-5 atoms each) to audit every atom under packages/design-system/src/atoms/ in parallel against COMPONENT_GUIDELINES.md rules; merges per-worker rows into ATOM_AUDIT.md table. Use when atom count >= 6 (per cost-effectiveness threshold) AND COMPONENT_GUIDELINES.md exists. Do not use when atom count < 6 (use atom-audit single-agent), when COMPONENT_GUIDELINES.md is missing, or when only 1-2 atoms changed (use design-spec-review per-component).

Produce ATOM_AUDIT.md table auditing every atom component against COMPONENT_GUIDELINES.md (memo, callbacks, inline styles, press anim, touch target, a11y, reduced motion). Output is the table; fixes flow through normal slice pipeline. Use when 2-4 weeks have passed since last audit, when 5+ new atoms shipped, or when COMPONENT_GUIDELINES has a new normative rule. Do not use when no atoms exist (run design-bootstrap first) or when only a single atom needs review (use design-spec-review instead). For 6 or more atoms, use atom-audit-fleet.

Read-only board-of-record view for an autonomous-run task (ADR-0044 D7, wos/autonomous-track.md). Renders the run as the spec, the IMPLEMENTATION_PLAN waves and slices, and the TASK_STATE phases mapped to to-do / in-progress / escalated / proposed / done columns, sourced only from the Fhorja task artifacts. No external work tracker; no writes. Use when the maintainer wants a single-glance status of an autonomous run without opening every artifact. Do not use to change state (use sync-task-state), to assess a normal multi-slice task (use where-we-at), or to route the next command (use what-next).

Drive an approved, waved IMPLEMENTATION_PLAN through the autonomous delivery track. A thin code-orchestrated dispatcher over the existing fleet primitives (the Workflow tool, implement-approved-slice as single writer) bounded by two human gates and a runtime governor. Runs verifiable slices with little supervision and emits PROPOSED slice diffs only; it never merges. Use when the plan is approved (approve-plan), broken into dependency-ordered waves, and the maintainer wants the work between the two gates run hands-off in a single supervised session. Do not use when the plan is not yet approved (run approve-plan), the work is a single slice (use implement-approved-slice), the run would need to remove the human merge gate or auto-merge (never allowed; a human always performs the merge), or cross-session durable resume (restart and re-attach of a stopped run) is required (out of v1 scope; a detached single continuous background session is in scope via the opt-in background mode).

Produce a staff-grade backend system-design RFC for the active task: a 12-section design document (problem, requirements, architecture, data model and storage, API contract, caching, scaling and bottlenecks, reliability and SLOs, security, observability, rollout and migration, trade-offs) for a new service, endpoint, or backend feature, persisted as BACKEND_SYSTEM_DESIGN.md. Capability-routed, not stack-specific; composes with slo-define, performance-budget, api-contract-review, and release-plan rather than duplicating them. Use when a backend service or feature needs an architecture-level design before planning and slicing. Do not use to slice an already-designed change (use implementation-plan), to analyze blast radius (use impact-analysis), to review an API contract in isolation (use api-contract-review), to design the frontend surface (use frontend-system-design), or with no active task folder (run task-init first).

Return a branch name and a concise commit message (at most 2 lines) for the current task, grounded in the real `git diff` rather than a paraphrase of the task summary. Use when the user only needs quick branch and commit naming right before committing, full PR packaging is unnecessary, and there is a real inspectable diff (staged or unstaged changes, or a branch diff vs an integration base). Do not use when the task needs a complete PR package (use pr-package), there is no diff yet (naming a branch from a task summary alone is the failure mode this command exists to avoid; ask the user to stage at least one change first), or the diff is still too unclear to summarize safely.

Append a single observation, question, hypothesis, or concern to TASK_STATE.md as task memory without disrupting in-progress work or requiring a full state sync. Lean append-only; never restructures other artifacts. Use when something surfaces mid-work that should be remembered for later (during planning, implementation, or review), when you noticed something not actionable now but should not be lost, when you want to log a hypothesis to validate before closure, or when a small concern does not justify decision-interview or targeted-questions but deserves to be on record. Do not use when the observation is a canonical decision (use decision-interview or sync-task-state), invalidates the current direction (use direction-adjust), requires several artifact changes (use sync-task-state or state-reconcile), or when there is no active task folder yet (run task-init first).

Pull external references (URLs or topics provided by the user) from the web, summarize each with a defined freshness format, and append them to projects/<client>__<project>/REFERENCES.md so all current and future tasks under that project can consume them as grounded external context. Deduplicates by URL. Use when the user wants to research and persist project-level references (stack docs, API contracts, regulations, competitor pages), supplies URLs to summarize with freshness metadata, surfaces an external reference that should outlive the task, or wants to seed REFERENCES.md for a freshly bootstrapped project. Do not use when the project folder does not exist yet (run project-bootstrap first), the reference is internal to a single task, the input is a codebase observation (use capture-observation), or the input is a decision or policy choice (use decision-interview or direction-adjust).

Generate and re-sync an AI-readable code context map (a ranked, token-budgeted, layered Markdown map of files, imports, signatures, invoke edges, and typed external boundary calls: db/http/queue) for a target project (or, from a seed file, its import chain), written to a gitignored folder inside that project and regenerated on invoke. Extraction is ripgrep-based by default, with optional parser augmentation when a parser is already present; no embeddings. The map is a seed for grep, not a replacement for reading code. Opt-in; not part of default task init. Use when an assistant needs fast structural orientation before editing a codebase, when onboarding to an unfamiliar repo, or when an existing map is stale. Do not use to locate one specific behavior (use code-locate), to analyze the blast radius of a planned change (use impact-analysis), to introspect a database schema (use db-context-supabase), or without a target codebase path.

Given a behavior description, locate candidate code paths and line ranges in the active codebase that probably implement it. Output up to 10 candidates with HIGH/MEDIUM/LOW confidence, one-line rationale per candidate, and an explicit search trail; propose a SOURCE_OF_TRUTH.md update so the next workflow step (typically impact-analysis) runs with concrete files instead of a vague codebase pointer. Per-repo when multi-repo. Use when the first real step is "where is this code?" (file paths not yet known), SOURCE_OF_TRUTH.md names the codebase but not specific files, you are about to run impact-analysis and the file list is missing, the user has a clear behavior description but no path or file pointers, or a failing test or runtime symptom names a behavior but not the implementation file. Do not use when file paths are already explicit, the codebase is tiny and the layout is known, the need is general architectural understanding (use impact-analysis), or no active task folder exists yet.

Senior design-system color contrast architect enforcing WCAG 2.2 AA/AAA per design context (normal text, large text, UI components, focus indicators). Audits every documented foreground and background pair across light and dark themes BEFORE the visual choices lock, producing a pairwise contrast matrix with token-level remediation. Activates when design-bootstrap proposes color tokens without contrast pairs, when DECISIONS.md proposes a primary or accent color without confirming contrast, when foundations/color.md exists without a contrast matrix, or when a screen-spec or component-spec mentions an unvalidated pair. Do not use for a single pair (use component-spec inline), when the design system has no theme variants, when no accessibility target is locked (raise via decision-interview first), or after remediation is agreed (use implement-approved-slice).

Produce a lossy compaction summary of TASK_STATE.md when task memory has grown beyond a useful working size, preserving canonical decisions and recommended next step while dropping stale facts. Distinct from sync-task-state (incremental, append-only, never lossy) and state-reconcile (drift repair, no shrinking). Use when task memory has accumulated across multiple slices (5+ completed) and feels heavy, the resume cost is growing as the file scales, the current known facts list is full of resolved or routine entries, or before a session pause where a slim TASK_STATE will speed restart. Do not use when the task is still in early discovery (memory is small), the artifacts disagree across files (use state-reconcile first), an incremental sync would be sufficient (use sync-task-state), or no active task folder exists yet (run task-init first).

Generate a 15-section component specification from a Figma component using MCP tools (get_design_context, get_screenshot, get_variable_defs). Produces a spec doc matching the COMPONENT_SPEC.md template with anatomy, variants, sizes, states, accessibility, motion, haptics, platform, security, performance, and API sections pre-filled from Figma observations. Use when documenting a design system component. Do not use when the component has no Figma representation or when the spec already exists (edit manually instead).

Harden the current decision set into a clean, normative source of truth with no residual ambiguity, then persist the result in DECISIONS.md and TASK_STATE.md as explicit reviewable edits (no silent intent drift). Use when key decisions are already resolved, the task has a stable contract or policy direction, and the remaining work is to harden wording and remove interpretation risk before planning or implementation. Do not use when major ambiguities remain unresolved, the task still needs decision-interview or resolve-contract-gaps, or the task is still in broad discovery.

Validate that a generic Postgres database (GCP Cloud SQL, GKE Autopilot, self-hosted, etc.) is reachable via psql or pg_dump, introspect a user-scoped subset of the schema (extensions, tables, columns, indexes, foreign keys, and optionally RLS policies and functions), and persist the result as DB_CONTEXT.md inside the active task folder; adds a single ## DB context cross-link in SOURCE_OF_TRUTH.md. Read-only introspection only; never destructive SQL. Opt-in, not part of default task init. Use when the active task touches a non-Supabase Postgres database (Cloud SQL, GKE Autopilot Postgres, self-hosted Postgres, RDS, etc.), when planning or implementation needs verified schema rather than assumed schema, or when an existing DB_CONTEXT.md is stale. Do not use without an active task folder (run task-init first), when the task does not touch a database, when the target is Supabase (use db-context-supabase), or when the user wants to record a schema decision (use decision-interview).

Validate that a Supabase MCP server is reachable, introspect a user-scoped subset of the database (tables, columns, types, RLS policies, optionally functions and recent migrations), and persist the result as DB_CONTEXT.md inside the active task folder; adds a single ## DB context cross-link in SOURCE_OF_TRUTH.md. Read-only introspection only; never destructive SQL. Opt-in, not part of default task init. Use when the active task touches Supabase data/schema/RLS, when planning or implementation needs verified schema rather than assumed schema, or when an existing DB_CONTEXT.md is stale. Do not use without an active task folder (run task-init first), when the task does not touch Supabase, when the database is not Supabase, or when the user wants to record a schema decision (use decision-interview).

Ask the minimum set of high-value decision questions needed before turning the task into canonical implementation rules. Decisions that would change runtime behavior, data integrity, rollout safety, or test strategy. Use when the missing information is decision-driven (not factual), different answers would change behavior or data integrity or rollout safety or test strategy, or the task cannot safely move into planning because policy or behavior is undecided. Do not use when missing information is factual (use targeted-questions), decisions are already locked in code or docs or approved task artifacts, or the task is already in implementation with no correctness-critical ambiguity. To harden wording before planning, use contract-signoff; to reconcile contradictory rules, use resolve-contract-gaps.

Generate an outward-facing delivery artifact (executive summary, slack or email update, demo script, release note, blog post draft) from the current task's work, scoped per audience and per format. Persists as DELIVERY_ASSET_<format>_<audience>.md inside the active task folder. Distinct from pr-package (GitHub-scoped) and team-update (team-internal). Grounds every claim in TASK_STATE.md, DECISIONS.md, IMPLEMENTATION_PLAN.md, and PR_PACKAGE.md when present; never invents metrics, customer impact, or marketing claims. An opt-in mode can send the asset to a connected knowledge-base MCP after a per-post confirmation. Use when delivery requires audience-specific framing beyond a PR description or team status update (executive readout, customer-facing release note, all-hands demo script, partner email). Do not use when the audience is a code reviewer (use pr-package), for a quick team status update (use team-update), when it is a reviewer note for PR_PACKAGE.md, or with no active task folder (run task-init first).

Bootstrap a design system from a Figma file using MCP tools. Extracts token variables, identifies components, creates the directory structure, and generates scaffolded foundation docs and a component inventory. Use when starting a new project with a Figma design file. Do not use when the design system docs already exist or when there is no Figma file.

Review a component or screen implementation against its spec doc for alignment on variants, states, accessibility, tokens, and visual fidelity. Distinct from review-hard (general risk) and repo-consistency-sweep (pattern matching). Activates when a slice's declared Scope touches a design-system button, icon, or component convention file (a shared atom/component under a design-system package) with no cited design-spec-review pass for that change. Use when a design system component or screen has been implemented and you want to verify it matches the documented spec. Do not use when no spec exists (write one first with component-spec or screen-spec).

Capture a small-to-medium course correction the user realized mid-task (not from external review), record it as a numbered D-N entry in DECISIONS.md, update TASK_STATE.md to reflect the adjusted direction, and route back to the appropriate command. Use when you are mid-task (any phase past discovery) and realize the direction needs adjustment, the realization came from your own work (not external review), the change is meaningful enough to record but does not invalidate the whole approach, and the existing slice or phase is recoverable with a small change of plan. Do not use when the trigger is external review or PR feedback (use pr-feedback-ingest or post-review-pivot), the realization invalidates the entire task scope (use task-init for a new task), the adjustment is too small to record (use capture-observation), the realization is loop or confusion (use im-stuck), the adjustment requires reopening locked decisions (use decision-interview), or no active task folder exists yet.

Orchestrator-workers variant of external-research for multi-modal sweep across distinct angles or source-groups of one research question. Promotes external-research's inline delegation to a first-class orchestrator with a worker contract and provenance. Sonnet orchestrator dispatches N Sonnet workers (one angle each) in parallel; each produces a structured per-angle synthesis grounded in REFERENCES.md; orchestrator merges into a single EXTERNAL_RESEARCH.md with cross-angle reconciliation (reinforcing vs contradicting vs different-framing). Use when the research question has N >= 3 distinct angles or source-groups AND the question would benefit from parallel deep reads. Do not use when 1-3 sources suffice (use external-research inline), when one source already dominates (no parallelism gain), or when sources have not yet been captured (run capture-references first).

Synthesize multiple external sources into a task-scoped EXTERNAL_RESEARCH.md grounded in REFERENCES.md entries. Each source is captured first via capture-references (project-level memory; deduplicated by URL); this command produces the synthesis with comparative analysis and a model recommendation visually separated from the source-grounded findings. Never invents claims; grounds every conclusion in a captured source. Use when the task depends on multiple external sources (vendor comparisons, regulatory evaluations, framework choices), when synthesis (not just capture) is needed, or when planning is blocked until external context is digested. Do not use when a single source suffices (use capture-references), when the research is project-level (use capture-references), when the question is internal (use code-locate or impact-analysis), or when no active task folder exists yet (run task-init first). For 3 or more distinct angles, use external-research-fleet.

Extract canonical foundations docs (`foundations/color.md`, `foundations/typography.md`, `foundations/spacing.md`, `foundations/radii.md`) from a batch of existing SCREEN_SPECs. Idempotent: re-runs only add new tokens, never overwrite existing role mappings, and route conflicts to a Review queue. Use when SCREEN_SPECs already document raw values and you need to converge them into role tokens. Do not use when foundations are already curated and screens already reference role tokens (run `foundation-audit` instead).

Orchestrator-workers variant of feature-library-scout for deep per-feature-problem library research. The orchestrator derives the feature-problem list and dispatches one Sonnet worker per problem; each worker ranks candidate libraries by adoption signal (registry downloads, dependents, last release, stars and trend, maintenance, framework/platform fit) relative to the project's ecosystem, grounded in captured REFERENCES.md sources, and returns a typed payload via StructuredOutput; the orchestrator is the sole writer that merges into one FEATURE_LIBRARIES.md and runs the orphan-scan gate (ADR-0038, ADR-0045). Stack-agnostic (npm, PyPI, crates.io, Go, Maven). Use when the product has 3 or more distinct feature problems that each warrant a deep multi-angle read. Do not use for 1-3 problems (use feature-library-scout inline), to pick stack layers (use stack-recommend), to verify framework pattern currency (use stack-currency-check), or with no active task folder (run task-init first).

Research and recommend community-vetted best-in-class libraries for each feature problem in the product (lists, camera, forms, keyboard, sheets), ranked by adoption signal (downloads, dependents, recency, stars-trend, maintenance, platform fit) relative to the project's ecosystem. Stack-agnostic across registries (npm, PyPI, crates.io, Go, Maven). Researches five angles (web, repo, registry, AAA practices, reference repos) and writes FEATURE_LIBRARIES.md, grounding every pick in a captured REFERENCES.md source; picks are optional guidance. Use when the stack is chosen and you want the canonical per-feature libraries surfaced and vetted. Do not use to pick stack layers (use stack-recommend), to verify a framework's current patterns (use stack-currency-check), to synthesize already-captured sources (use external-research), or with no active task folder (run task-init first). For a deep per-problem sweep, use feature-library-scout-fleet.

Compare design tokens in code against foundation docs and optionally Figma variables to detect drift (tokens added without documentation, documented tokens not in code, value mismatches). Use when the design system has been evolving and you want to verify foundations are in sync. Do not use when no foundation docs exist (run design-bootstrap first).

Review a frontend architecture at scale and gate micro-frontend adoption BEFORE building. The first step is an adopt-or-don't-adopt decision (default: you probably do not need micro-frontends; prefer a modular monolith until 3 or more independently deploying teams and real coordination pain exist), then a checklist covering team-and-domain boundaries, independent deployability, governed shared dependencies, design-system sharing, runtime isolation, cross-app communication, routing and composition tier, rendering strategy, state at scale, a performance budget across the composition, and governance and failure handling. Capability-routed, not stack-locked. Use when reviewing a frontend architecture, evaluating whether to adopt micro-frontends, or hardening a multi-team frontend before it scales. Do not use to design one system (use frontend-system-design), to review a GraphQL or REST contract (use graphql-contract-review or api-contract-review), or with no active task folder (run task-init first).

Produce a staff-grade frontend system-design RFC for the active task: a 12-section design document (problem, requirements, architecture, data model, API and interface contract, rendering and delivery, state management, performance budget, accessibility, security, rollout, trade-offs) covering web and mobile, persisted as FRONTEND_SYSTEM_DESIGN.md. The default mode writes the design doc for real work; an --interview mode reframes the same structure for a frontend system-design interview round (RADIO-aligned). Capability-routed, not React-specific. Use when a frontend feature or surface needs an architecture-level design before planning and slicing, or when preparing a system-design interview artifact. Do not use to frame whether the problem is right (use problem-framing), to slice an already-designed change (use implementation-plan), to analyze blast radius (use impact-analysis), to review an API contract in isolation (use api-contract-review), or with no active task folder (run task-init first).

Verify a built Godot 2D scene at runtime: run the scene (press-play or headless), read the captured debugger output, classify any runtime errors against a Godot-specific taxonomy, and decide a PASS/FAIL runtime gate for the slice's acceptance behavior. The run's real output IS the Layer-1 runtime evidence (ADR-0048); a claimed-but-not-shown run is unverified. MCP-agnostic about how the scene is run; it verifies and routes fixes, it does not apply them. Use after a Godot slice is implemented to gate runtime behavior the static checks (lint, typecheck) cannot catch. Do not use to plan a scene (use godot-scene-plan), to write or fix the code (use implement-approved-slice or implement-slice-complement), to triage a failure into a fix size (use incident-triage), or with no implemented scene to run.

Plan the Godot scene and node structure for a 2D game feature before any GDScript is written: the scene tree, node types and responsibilities, autoloads (singletons), signal wiring, the input map, and the resources and sub-scenes to create. Produces GODOT_SCENE_PLAN.md, a design-time plan an MCP-driven editor or a human then builds against. Capability-routed and MCP-agnostic (names no specific server). Consults the Godot reference topics (architecture, interaction-and-feel) for save-state, touch, and feedback-layer depth. Use when a Godot 2D feature or screen needs its scene architecture decided before implementation. Do not use to frame whether the game idea is right (use problem-framing in its game-design mode), to slice an already-planned build (use implementation-plan), to analyze blast radius of an existing Godot project (use impact-analysis), to verify a running scene (use godot-runtime-verify), or with no active task folder (run task-init first).

Review a GraphQL schema and a Backend-for-Frontend (BFF) contract BEFORE implementation, against a GraphQL-specific checklist: schema shape and nullability (null-bubbling), errors-as-data unions, N+1 and DataLoader, query cost and depth limits, cursor-connection pagination, federation entity ownership, breaking-change gate (schema checks), auth layering and BFF token posture, BFF thinness, and partial-failure degradation. Distinct from api-contract-review (REST and HTTP) and review-hard (post-implementation risk). Capability-routed, not stack-locked. Use when designing a new GraphQL schema, a federated subgraph, or a BFF contract, or modifying an existing one. Do not use for a REST contract (use api-contract-review), when the schema is already implemented (use review-hard or repo-consistency-sweep), or with no active task folder (run task-init first).

Scan the current working session and the active task's artifacts for reusable, generalizable lessons (what was tried, what failed and why, what surprised us, what the next task should do differently) and propose anchored entries to append to the task's LEARNINGS.md, the produce-side counterpart to the ADR-0017 consume path that task-init already reads. Append-only and read-only on existing entries; de-duplicates against what is already captured; keeps durable lessons and drops one-off task trivia. Use on demand mid-task after a hard-won fix or a surprising failure, or at closure to sweep a long session before the context is lost. Do not use to rewrite or prune existing learnings (never edit prior entries), to capture a single in-flight observation (use capture-observation), to close a slice or the task (use slice-closure or task-close), or when nothing durable was learned (return a NO_OP rather than manufacturing a lesson).