create-religion 0.1.0

package/template/.agents/skills/discovery/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: discovery
+summary: a guided planning conversation that drafts the two plans
+description: "An optional multi-turn planning conversation that develops a project plan and build plan through adaptive questioning, then drafts both files and writes them only after explicit approval. Never required: the plans can always be written directly or developed in any conversation. Use only when the user runs $discovery, asks for a guided planning session, or wants help thinking a product through before writing the plans. Do not suggest it merely because the plans are empty."
+---
+
+# discovery - think the project through, then draft the plans
+
+Optional. The plans can be written directly, and often should be. This exists for when
+someone wants the questions asked.
+
+Never suggest this as the default next step after installation. An empty plan is not a
+reason to start an interview.
+
+## How this runs
+
+A conversation over as many turns as it takes, then a draft. Nothing is written until the
+user says the drafts are right.
+
+Ask a few questions at a time, not a form. Follow what the answers actually say: a project
+with no users to speak of does not need three questions about user tiers, and a project
+whose whole difficulty is the data model deserves more than one.
+
+## What to establish
+
+Enough to fill the required plan sections, and nothing more.
+
+**The problem.** What is broken or missing, and for whom. Push past the first answer, which
+is usually a solution wearing a problem's clothes: "people need a dashboard" is a solution.
+Ask what goes wrong today without it.
+
+**The users.** Who specifically, and what each needs. If the answer is "everyone", the
+project has no users yet and that is worth knowing now.
+
+**The features.** What the first version has to do. Then ask what it deliberately does not
+do, which is the more useful question and the one nobody volunteers.
+
+**The data.** What the project works with: stored entities, or the shapes it reads and
+emits, or the interface it exposes. Ask what shape later work will depend on, since that is
+what becomes expensive to change.
+
+**The stack.** What it is built with, and anything already decided or already ruled out.
+
+Then the optional sections, only where they apply: how it makes money, how it should look
+and feel, where it deploys.
+
+## Things worth pushing on
+
+- **Vagueness that will become a decision later.** "Some kind of auth" becomes a spec
+  someone has to write. Ask now.
+- **Scope that grew during the conversation.** Say so, and ask what the first version drops.
+- **Contradictions.** Note them as they appear rather than collecting them for the end,
+  where they will be an unpleasant list.
+- **The build order.** What has to exist before what. That is what the build plan encodes.
+
+## Drafting
+
+When the user says they are ready, show both drafts **in full, in the conversation**, before
+writing anything.
+
+- **Project plan** - as much depth as the answers support. Include the rationale,
+  constraints, and exclusions, since those are what later work needs and what a plan
+  usually loses.
+- **Build plan** - a numbered checkbox list of feature-sized items in rough build order. No
+  detail; the depth belongs in each spec.
+
+Mark anything you supplied rather than heard. A draft that quietly invents a monetization
+model reads as though the user decided it.
+
+Then ask for changes, and iterate. Write both files only after an explicit yes.
+
+## Rules
+
+- Nothing is written before approval, including a partial draft "to make it concrete".
+- The plans are the user's. Draft in their terms, not in yours.
+- Do not fill a section the conversation did not cover. Leave it, and say what is missing.
+- Stop when the plans are usable, not when they are exhaustive. $overview will flag
+  what is genuinely too thin.
+
+## Formatting
+
+Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
+markdown, lists for enumerations and tables for matrices rather than dense paragraphs.

package/template/.agents/skills/distill/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: distill
+summary: promote proven observations from the journal into loaded lessons
+description: "Read religion/learning/journal.md, promote observations that have proved stable into religion/learning/lessons.md, fold corrections about this project into its coding standards, and archive what was processed. Lessons are loaded every session, so promotion is deliberately strict: an observation earns a place only once it has recurred or been confirmed. Use when the user runs $distill, asks to consolidate what has been learned, or when the journal has grown enough to be worth a pass."
+---
+
+# distill - turn observations into lessons
+
+The journal is cheap and unfiltered: anything surprising goes in. Lessons are expensive,
+because they are loaded into every session forever. This skill is the gate between them.
+
+## What goes in the journal, and when
+
+Any skill appends to `religion/learning/journal.md` when something is worth remembering:
+
+- a correction from the user, especially a repeated one
+- an assumption that turned out to be wrong about this project
+- a failure whose cause was non-obvious
+- a convention discovered in the code that no document states
+
+One entry, dated, in a sentence or two. What happened and what it implies. Appending is
+cheap and unreviewed; nothing is loaded from here.
+
+Do not journal the ordinary. "The build passed" is not an observation.
+
+## Step 1 - read and group
+
+Read the journal. Group entries that are really the same observation seen more than once.
+Recurrence is the main evidence that something is a lesson rather than an incident.
+
+## Step 2 - decide what has earned promotion
+
+Promote an observation only when it is all of these:
+
+- **Confirmed**, not suspected. Either seen more than once, or explicitly corrected by the
+  user.
+- **General**, not incidental. It will apply again, to work not yet started.
+- **Actionable**. It changes what someone would do, not just what they would know.
+- **Not already written down.** If it belongs in the coding standards or the project plan,
+  it goes there instead, where it is already loaded and already owned.
+
+Everything else stays in the journal or is dropped. A single surprising incident is not a
+lesson; it is an incident.
+
+## Step 3 - route by kind
+
+Two destinations, and the distinction matters.
+
+**About this codebase** goes to `religion/context/coding-standards.md`. "Server actions in
+this project take the organization identifier from the session, never from arguments" is a
+convention, and conventions belong with the conventions. Propose the exact edit and wait:
+the standards are the user's file.
+
+**About how work goes here** goes to `religion/learning/lessons.md`. "Schema changes in
+this project need the migration and the type change in the same step, or the typecheck
+fails halfway through review" is a lesson about working, not a coding convention.
+
+## Step 4 - write, keeping it short
+
+Each lesson is two or three lines: what to do, and why, since a lesson without its reason
+gets discarded the first time it is inconvenient.
+
+**Keep the file short.** It is loaded every session, so every line is paid for constantly.
+Before adding, look for a lesson that is now wrong, superseded, or has become obvious
+because the code changed, and remove it. A lessons file that only grows becomes a file
+nobody reads, which is worse than no file.
+
+If the file is getting long, that is a finding: report it rather than adding to it.
+
+## Step 5 - archive what was processed
+
+Remove promoted and rejected entries from the journal, appending them to
+`religion/learning/journal-archive.md` with what was decided. Nothing is deleted outright:
+a rejected observation that recurs is exactly the evidence that promotes it next time.
+
+## Step 6 - report
+
+- entries read, grouped, promoted, and rejected, with the reason for each rejection
+- lessons added, and any removed
+- standards edits proposed, and whether they were approved
+- whether the lessons file is getting too long
+
+## Rules
+
+- Promote on evidence, never on a good story. One incident is an incident.
+- Codebase conventions belong in the standards. Do not duplicate them as lessons.
+- Standards edits are proposed and wait. That file belongs to the user.
+- Remove as readily as you add.
+- Never promote something that is really a bug. That is a finding, and it belongs in the
+  ledger.
+
+## Formatting
+
+Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
+markdown, lists for enumerations and tables for matrices rather than dense paragraphs.

package/template/.agents/skills/doctor/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: doctor
+summary: check the setup is healthy and explain anything that is not
+description: "Read-only health check of the installation: required files present, adapter trees in sync, the entry file's commands accurate, configuration valid, plans usable, overview fresh, ignore rules sane, and git state workable. Runs the religion command-line tool for the deterministic checks when it is installed, then explains what any failure means and offers the fix. Use when the user runs $doctor, asks whether the setup is correct, wants a health check, or says something feels wrong before starting or resuming work."
+---
+
+# doctor - is this set up correctly
+
+$status says where the work stands. This says whether the machinery around it is
+sound. Read-only.
+
+## Step 1 - run the checks
+
+If the `religion` command is available, run `religion doctor --json`. Every check it
+performs is deterministic, so a program should perform it.
+
+Otherwise check directly:
+
+- **Files** - `religion/config.json`, both plans, the four context files, and the history
+  and reference directories exist.
+- **Configuration** - `config.json` parses, and every key and value is one the schema
+  allows. An unknown key is usually a typo, and a typo silently means the default.
+- **Adapters** - for each installed tree, the skills present and, when more than one tree
+  exists, whether they hold the same skills.
+- **Entry file** - the Commands section is filled in rather than the shipped placeholder,
+  and the commands it names exist in the project.
+- **Plans** - required sections answered, build plan is a checkbox list.
+- **Overview** - present, and its source hash matches the current plans.
+- **Ignore rules** - the state directory is either committed or ignored deliberately, not
+  half of each, and nothing secret is about to be committed.
+- **Git** - a repository exists, and it is not in a detached or mid-operation state that
+  will surprise the loop.
+
+## Step 2 - explain, do not just list
+
+For each failure, say what it means and what it will cause. "Overview hash mismatch" is
+not useful on its own; "the plans changed after the overview was generated, so the next
+spec would be written against a data model that no longer matches" is.
+
+Order by what actually blocks work. A missing history directory blocks the first
+completion; an unfilled Commands section blocks verification; a cosmetic gap blocks nothing
+and should be reported last or not at all.
+
+Offer the fix, and where it is a single obvious action, offer to make it. Regenerating a
+stale overview or creating a missing directory needs no deliberation. Anything touching the
+plans, the configuration, or git is proposed and waits.
+
+## Step 3 - report
+
+- **Healthy** or **N problems**, stated first.
+- Each problem: what is wrong, what it will cause, how to fix it.
+- What was checked, briefly, so the absence of a warning means something.
+- Next action.
+
+## Rules
+
+- Read-only by default. Fixes are offered and only made with a yes.
+- Do not report a problem that is a deliberate choice. A project with no test runner has
+  not failed a check; testing is opt-in.
+- Never claim a check passed that could not run.
+
+## Formatting
+
+Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
+markdown, lists for enumerations and tables for matrices rather than dense paragraphs.

package/template/.agents/skills/extend/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: extend
+summary: author a new skill for this workflow, with its routing tests
+description: "Add a capability to Religion itself: interview for what the skill must do, write its source with the required frontmatter, add routing tests that prove the right skill is selected for a request, render it into every adapter tree, and verify. Refuses to add a skill whose job an existing one already does, since an overlapping roster routes badly and the cost lands on every later request. Use when the user runs $extend, asks to add a skill or command to the workflow, or asks to extend Religion."
+---
+
+# extend - add a capability to the workflow
+
+This edits the workflow itself, not a project built with it. Run it in a Religion source
+checkout, where `src/skills/` exists. In an installed project there is nothing here to edit.
+
+## Step 1 - argue against it first
+
+A new skill is a permanent addition to a roster that every request is routed against. The
+cost is paid by every later request, not just the ones that use it.
+
+Read the existing roster and ask:
+
+- **Does an existing skill already own this?** If so, extend that one. A mode or an
+  argument is nearly always better than a sibling: it keeps related behavior together and
+  adds no routing ambiguity.
+- **Would this be selected reliably?** If a request that should reach it would plausibly
+  reach another skill, both get worse. Overlapping descriptions are the main way a roster
+  degrades.
+- **Is it a skill at all?** A deterministic check belongs in the command-line tool. A rule
+  belongs in the constitution or the standards. A one-off belongs in the conversation.
+
+Say what you concluded. If an existing skill should absorb it, propose that instead and
+stop. Being talked out of a new skill is a successful outcome here.
+
+## Step 2 - establish what it does
+
+- **The job**, in one sentence. If that takes two, it is two skills or it is a mode.
+- **When it should be selected**, and just as importantly when it should not, named against
+  the skills it sits closest to.
+- **What it reads and what it writes.** Every state file has exactly one writer; a new
+  writer for an existing file needs a reason and a rule for the overlap.
+- **What it must never do**, beyond the authority tiers.
+- **Where it sits in the loop**, and which skills hand to it or receive from it.
+
+## Step 3 - write the source
+
+Create `src/skills/<name>/SKILL.md` with frontmatter carrying `name` matching the
+directory, `summary` as a short clause for the roster, and `description` as the long
+routing text.
+
+**The description is what routing runs on.** Write it as the situations that should select
+this skill, in the words a user would actually use, and name the neighbours it must not be
+confused with. A description written as a feature list routes badly.
+
+Reference other skills and paths through the token vocabulary rather than writing literal
+syntax: the command token takes a skill name and renders that tool's own invocation, and
+the state token renders the state directory. A literal slash is correct for one tree and
+wrong for the others, and a literal directory name breaks if the system is ever renamed.
+The vocabulary is defined in `src/lib/adapters.ts`.
+
+Then the body: where it sits, its steps, its rules, and the formatting pointer. Match the
+existing skills, which say **why** a rule exists rather than only stating it, because a rule
+whose reason is written survives contact with a case its author did not foresee.
+
+## Step 4 - register and render
+
+Add the name to the planned roster in `src/lib/skills.ts`, or the reference check will
+reject every mention of it.
+
+Run the build, which renders it into every adapter tree, then run the verification, which
+confirms the frontmatter is complete, no token is unrendered, every reference resolves, and
+nothing drifted.
+
+## Step 5 - prove it routes
+
+Add `evals/routing/<name>.json`: prompts that must select this skill, and prompts belonging
+to neighbouring skills that must not.
+
+The negative cases matter more. A skill that fires when it should is easy; a skill that
+stays quiet when a neighbour should have fired is what keeps a large roster usable. Write
+the confusable cases deliberately, not the obvious ones.
+
+Run the routing evaluation. A regression in a **neighbouring** skill's score is the expected
+failure mode: the new description pulled requests away from it. Fix it by narrowing the
+descriptions until each request has one clear owner.
+
+## Step 6 - wire it in
+
+A skill nobody reaches is not a capability. Update whatever should point at it: the entry
+files if it changes the loop, the interaction guide if it changes the sequence, the skills
+that should hand off to it.
+
+Report what was added, what it routes on, its eval results, and every file changed.
+
+## Rules
+
+- Argue against it first, honestly.
+- One job per skill. Two sentences means two skills, or a mode on one.
+- The description is routing, not marketing.
+- Never ship a skill without its routing tests.
+- Never edit a rendered tree. Edit the source and rebuild.
+
+## Formatting
+
+Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
+markdown, lists for enumerations and tables for matrices rather than dense paragraphs.

package/template/.agents/skills/feature/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: feature
+summary: turn a build-plan item into a reviewed, buildable spec
+description: "Turn a feature from the build plan into a buildable spec in religion/context/current-work.md. With no argument it specs the first unchecked item; given a number or name it specs that one; add `preview` to get a read-only briefing that writes nothing. A genuinely new feature goes through an intake that proposes the plan line, waits for approval, and refreshes the overview before spec'ing. Sizes the work and splits anything too large into sub-items, writes small build steps with observable outcomes, then red-teams its own draft and reports what the critique changed before stopping for review. Use when the user runs $feature, names or numbers a feature, asks to start or break down the next feature, or asks what an upcoming feature involves."
+---
+
+# feature - turn a build-plan item into a buildable spec
+
+Where this sits:
+
+    build-plan.md  ->  [feature]  ->  current-work.md  ->  implement
+    (one line)         (spec it)      (the spec)          (build it)
+
+The build plan is deliberately thin: one line per item, no detail. Turning one of those
+lines into something buildable is this skill's whole job. It plans; it never builds.
+
+## Input
+
+- **No argument** - the first unchecked item in the build plan, including the first
+  unchecked sub-item under an item that was split.
+- **A number or name** - `$feature 3`, `$feature "login"`.
+- **A description with no match in the plan** - goes through **New work intake** below.
+- **`preview`** appended to any of the above - a read-only briefing, writing nothing.
+
+## Step 0 - make sure the ground is solid
+
+Two checks before anything else.
+
+**Overview freshness.** Recompute the source hash over the two plans. If it does not match
+the stamp in `religion/context/project-overview.md`, or the stamp is missing, follow the
+`$overview` skill first, report what changed, then continue here. A spec written
+against a stale overview encodes a data model the plans no longer describe.
+
+**Open questions.** Read the overview's Open questions section. If any of them lists an
+area this item touches in its `affects` line, the contradiction would be resolved by
+guessing while writing the spec. Instead:
+
+1. Name the question and quote what the two plans each say.
+2. Ask the user to decide.
+3. Show the exact edit their answer implies, in the plan section that is wrong.
+4. On approval, write it, follow `$overview` to regenerate, then continue.
+
+Only the user's own answer may resolve an open question, and only the edit they approved
+is written. If they would rather not decide now, stop and say which item remains blocked.
+
+An open question whose `affects` list does not cover this item does not block it.
+
+## Step 1 - pick the target
+
+Given a number or name that matches a build-plan item, use it. With no argument, read the
+plan top to bottom and take the first unchecked leaf. State which item you are spec'ing
+before going further.
+
+If the build plan is not a checklist yet, treat every item as unchecked, take the first,
+and offer to convert the list so progress can be tracked from here on. Proceed either way.
+
+### New work intake
+
+For a genuinely new capability, not a bug or small change. Those go to $fix.
+
+1. Search checked and unchecked items for an existing or near-duplicate item. If the
+   wording might just be a different name for something already planned, show the closest
+   matches instead of creating new scope.
+2. If it is genuinely new, propose one feature-sized checkbox line and where it belongs.
+   Preserve completed items and their numbers; take the next unused number.
+3. Check whether it materially changes product direction, users, data, stack, or
+   deployment. Include the exact proposed project-plan edits only when it does. Most
+   incremental work changes only the build plan.
+4. Stop for approval, showing the complete proposed plan change.
+5. After approval, write it, follow `$overview` to regenerate, then resume here with
+   the new item as the target.
+
+Never add scope to a plan the user owns without showing the exact change and waiting.
+
+## Step 2 - size it, and split if it is too big
+
+Read the target line, then take full context from the project overview: the data model,
+the stack, the conventions. Then decide how big this is.
+
+**Small enough to build and review as one unit** goes to Step 3.
+
+**Too big for one reviewable spec** gets split. Propose a short list of sub-items, title
+and one line each, let the user adjust it, then write them under the parent as an indented
+checklist (`4a`, `4b`, `4c`). Spec only the first now; the rest are picked up later.
+
+Two levels of breakdown, easily confused:
+
+- **Sub-items** are each big enough to stand alone: their own spec, review, and archive.
+- **Build steps** are small diffs inside one item.
+
+"Authentication" is too big for one spec, so it becomes `4a` registration, `4b` login,
+`4c` route protection. Inside `4a`, the page and its server action are steps, not items.
+
+This sizing call is exactly why the build plan stays high level.
+
+### Preview mode
+
+When the request ended in `preview`, stop here and report, writing nothing:
+
+- what the item is, in a sentence
+- what it depends on, and whether those are done
+- what it will touch: routes, models, modules
+- rough size, and how many steps it is likely to need
+- whether it will split, and into what
+- anything worth deciding before spec'ing it
+
+That is the whole of preview mode. Do not write the spec, touch the plans, or create files.
+
+## Step 3 - write the spec
+
+Write `religion/context/current-work.md` following `reference/spec-template.md`, filling
+every section.
+
+**Design reference.** If `prototypes/` exists, it is the reference and no image is needed.
+Check what is in it:
+
+- **Static mockups sharing a theme file** are throwaway. Link the relevant ones, treat the
+  theme as the source of truth for colour, type, and spacing, and make the **first build
+  step** port those tokens into the application's real stylesheet before any component is
+  built against them.
+- **Real components** are not throwaway. Link them and build on them directly. There is no
+  token-porting step, because the tokens are already the project's.
+
+If there are no prototypes and the work is visual or a replication of an existing design,
+ask for a screenshot, save it under `religion/reference/`, and link it. Do not write a
+visual spec from words alone when an image could exist.
+
+**Build steps** are the core of the file. Each is a small diff, ends with something that
+works, depends only on earlier steps, and carries an outcome that can actually be observed.
+Read the Commands section of the entry file while writing the Testing section, so predicted
+coverage matches the gate that is actually on.
+
+This is a draft. Do not present it yet.
+
+## Step 4 - red-team the draft, then tighten
+
+Turn on your own spec and try to break it. The cheapest place to catch a scope problem or
+an oversized step is here, before any code exists.
+
+- **Coverage.** What does this need that no step delivers? Push on what the happy path
+  skipped: empty, missing, or malformed input; the error, loading, and empty states; the
+  first-run case; failure of anything external it calls.
+- **Step size.** Would any step's diff be too large to read in one sitting? Split it.
+  Oversized steps defeat the review gate, which is the point of the whole loop.
+- **Order.** Does each step leave the project working, and depend only on earlier ones?
+- **Contracts.** Is any type, route, or stored shape that later work will touch left
+  undefined? Lock it now and mark it load-bearing.
+- **Scope honesty.** Is anything creeping in that belongs to a later item? Is anything
+  pushed out of scope that this item genuinely cannot ship without?
+- **Outcomes.** Is each one observable and checkable, or is it a vague "it works"?
+- **Visual fidelity.** If this is visual work, is a reference linked, or is it about to be
+  built blind from prose?
+- **Testing.** Does the predicted coverage match the gate that is on?
+
+Apply the fixes. Then stop and present the spec, leading with a short **what the critique
+changed** note: the splits, gaps, or scope cuts made, or "nothing, the draft held up".
+
+That note is the point. It shows the gate working before a line of code exists.
+
+## Rules
+
+- Small, reviewable steps. A diff too large to read means the step was too large.
+- Build in order. Each step leaves the project working.
+- Lock data contracts early and mark load-bearing shapes.
+- Scope honestly. State what is deferred so the item stays contained.
+- The plans belong to the user. Propose, show the exact change, and wait.
+- This skill plans. It never writes product code, and never starts building.
+
+## Formatting
+
+Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
+markdown, lists for enumerations and tables for matrices rather than dense paragraphs.

package/template/.agents/skills/feature/reference/spec-template.md

@@ -0,0 +1,67 @@
+# <Feature name>
+
+**Type:** Feature
+**From build plan:** item <n>
+**Status:** not started
+
+## Goal
+
+What this delivers, in a sentence or two, and why it matters. Someone reading only this
+section should know what will be true when the work is done.
+
+## Design reference
+
+For visual or replication work, link the reference here: the mockups under `prototypes/`
+when they exist, or an image saved under `religion/reference/`. Prose underspecifies a
+visual target, and the approximation costs more to correct than the reference costs to
+obtain. Delete this section when the work has no visual target.
+
+## In scope
+
+- The specific things this work includes.
+
+## Out of scope
+
+- What it deliberately does not touch, and which later item picks it up.
+
+## Build loop
+
+Build one step at a time, never the whole item at once.
+
+1. The step is planned before any code is written.
+2. Just that step is implemented, as the smallest change that satisfies its outcome.
+3. The diff is shown, not whole files, and explained in plain language.
+4. Its stated outcome is proved with evidence, then the step is approved.
+
+Never accept a step you have not read. If a diff is too large to review, the step was too
+large, so split it.
+
+## Build steps
+
+Small, reviewable units. Each ends with something that works, and each carries an
+observable outcome that can be checked. These boxes are ticked as the steps land, which is
+what lets a cleared context resume from the first unchecked one.
+
+- [ ] **Step 1 - <what it builds>** - what changes. *Done when:* <observable outcome>.
+- [ ] **Step 2 - <what it builds>** - what changes. *Done when:* <observable outcome>.
+
+## Files and areas
+
+- The files or modules this creates or changes.
+
+## Data and contracts
+
+- Types, stored shapes, or interface shapes involved, or "none".
+- Mark anything later work will depend on as load-bearing.
+
+## Testing
+
+- How the outcomes are verified, per step.
+- When a test command is declared, name the in-scope logic that needs a test: parsers,
+  formatters, validators, server actions. Not components or integration surfaces.
+- When no runner is configured, say so and rely on running it, a screenshot, and the build.
+
+## Notes for the agent
+
+- Conventions and constraints this work must respect, drawn from the coding standards and
+  the project overview. Anything that would be wrong in a way review would not catch.

package/template/.agents/skills/fix/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: fix
+summary: spec an unplanned bug or small change, or repair a recorded finding
+description: "Write a short spec for an unplanned bug or small change into religion/context/current-work.md so it runs through the same reviewed loop as planned work, then stop. Given a finding identifier instead, specs the repair of that recorded finding. Fixes are archived under religion/history/fixes/ and never touch the build plan. Use when the user runs $fix, reports a bug, asks to fix or change something that is not a planned item, or asks to pick up a finding from the ledger."
+---
+
+# fix - spec an unplanned change
+
+Same loop as planned work, smaller spec. A fix is not a build-plan item: it is not
+numbered, it ticks nothing, and it archives on its own.
+
+## Input
+
+- **A description** - `$fix "password reset email never sends"`. A problem stated in the
+  conversation already counts; this skill does not scan the project hoping to find
+  something wrong.
+- **A finding identifier** - `$fix F-03` specs the repair of that ledger entry.
+
+Without either, ask what is wrong. Do not guess.
+
+## Step 1 - understand the problem
+
+**For a described problem**, establish what actually happens before writing what should.
+Reproduce it if you can do so cheaply. If the cause is genuinely unclear and finding it
+would mean exploring, stop and point at $debug, which isolates a failure without
+changing anything. Writing a fix spec against a guessed cause produces a fix for the wrong
+problem.
+
+**For a finding**, read its entry in `religion/context/findings.md`: the file and line, why
+it matters, the suggested fix. The finding is the problem statement.
+
+If something is already in progress in `religion/context/current-work.md`, say so and ask
+whether to set it aside. One thing at a time is the point.
+
+## Step 2 - write the spec
+
+Write `religion/context/current-work.md` following the shape in
+`$feature`'s spec template, marked `Type: Fix`, with no build-plan number. Keep it
+short. A fix that needs a long spec is a feature that has not admitted it yet, and should
+go through $feature instead.
+
+Fill in:
+
+- **Goal** - what is wrong, and what will be true afterwards.
+- **Cause** - what actually produces the behavior, and how that was established. If the
+  cause is a guess, say so; a fix built on a guess needs review to know that.
+- **In and out of scope** - especially what nearby brokenness is deliberately not being
+  fixed now. Fixes sprawl more easily than features because the surrounding code is already
+  under suspicion.
+- **Build steps** - usually one or two, each with an observable outcome.
+- **Testing** - when a test runner is configured and the fix touches logic, the fix ships a
+  test that fails without it. A bug that could recur silently is exactly what the test gate
+  is for.
+
+For a finding repair, name the finding identifier in the Goal so the archive and the ledger
+agree about what happened.
+
+## Step 3 - stop
+
+Present the spec for review. This skill plans; $implement builds it.
+
+For a finding repair, note that implementation marks the finding `fixed` and only a later
+$audit moves it to `closed`.
+
+## Rules
+
+- A fix needs a real problem statement. Do not invent one.
+- Do not fix things nobody reported while you are in there. Note them instead.
+- If the fix turns out to be feature-sized, stop and say so rather than growing the spec.
+- Never mark a finding `accepted` or `invalid`. Those are the user's call and a review's
+  verdict.
+
+## Formatting
+
+Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
+markdown, lists for enumerations and tables for matrices rather than dense paragraphs.