From a2c3f50a67381521f369417b5453ffc93f864838 Mon Sep 17 00:00:00 2001 From: Cameron Date: Tue, 7 Jul 2026 01:18:12 -0700 Subject: [PATCH] prompts/: the dispatch library for sub-agent ticks Cameron wants paste-ready prompts for spinning up sub-agents on tailored ticks, runtime-agnostic (one-shot CLI agents or stateful Letta agents that accumulate experience over runs). New prompts/ directory: - README.md: the shared contract every prompt inherits (read order, worktree-first, the one rule, check.sh gate, direct merge to main, ledgers-merge-by-union, one-finding-per-run) plus memory guidance for stateful agents (record stable facts and dead ends, date everything, never trust memory over the tree). - Eight task prompts, each with Mission / Procedure / Definition of done / What to carry forward: implement-gap, find-contradiction, ask-the-human, harvest-issues, audit-implemented, legibility-pass, knowledge-sync, playtest-notes. AGENT.md tells dispatched agents the prompt is their work order. Defense: process-only, no game behavior; the prompts encode standing law (knowledge/tick.md's classifications, spec/meta.md's status semantics, the legibility clause, the worktree and union rules) into dispatchable form, serving the constitution's stated goal that agents can be pointed at one document and told: go. --- AGENT.md | 6 +++ DEVLOG.md | 20 +++++++++ prompts/README.md | 78 +++++++++++++++++++++++++++++++++++ prompts/ask-the-human.md | 62 ++++++++++++++++++++++++++++ prompts/audit-implemented.md | 57 +++++++++++++++++++++++++ prompts/find-contradiction.md | 65 +++++++++++++++++++++++++++++ prompts/harvest-issues.md | 63 ++++++++++++++++++++++++++++ prompts/implement-gap.md | 66 +++++++++++++++++++++++++++++ prompts/knowledge-sync.md | 60 +++++++++++++++++++++++++++ prompts/legibility-pass.md | 56 +++++++++++++++++++++++++ prompts/playtest-notes.md | 70 +++++++++++++++++++++++++++++++ 11 files changed, 603 insertions(+) create mode 100644 prompts/README.md create mode 100644 prompts/ask-the-human.md create mode 100644 prompts/audit-implemented.md create mode 100644 prompts/find-contradiction.md create mode 100644 prompts/harvest-issues.md create mode 100644 prompts/implement-gap.md create mode 100644 prompts/knowledge-sync.md create mode 100644 prompts/legibility-pass.md create mode 100644 prompts/playtest-notes.md diff --git a/AGENT.md b/AGENT.md index 7b82fff..c781875 100644 --- a/AGENT.md +++ b/AGENT.md @@ -19,6 +19,12 @@ this order: Status in the same commit, and treat conflicts with the constitution as tick findings, not judgment calls. +If you were dispatched with a prompt from **[prompts/](prompts/)** (the +task-type library: implement a gap, find a contradiction, raise a human +question, harvest issues, audit, legibility, knowledge sync, playtest), +that prompt is your work order and already encodes the rules above — +follow it end to end. + ## Start every session with a tick Before taking assigned work — and always when running autonomously — take a diff --git a/DEVLOG.md b/DEVLOG.md index d320e3f..3c63eb8 100644 --- a/DEVLOG.md +++ b/DEVLOG.md @@ -2,6 +2,26 @@ Reverse chronological implementation notes. Keep this factual: what changed, why, checks, and spec impact. +## 2026-07-07 - Process: prompts/ dispatch library + +- Intent: Cameron wants a folder of paste-ready prompts for spinning up + sub-agents on tailored ticks, agnostic to agent runtime (one-shot CLI + or stateful Letta agents that accumulate experience). +- Changed: new prompts/ directory — README.md (the shared contract: + read order, worktree, one rule, check.sh gate, direct merge, union on + ledgers, one-finding-per-run, stateful-memory guidance) plus eight + task prompts: implement-gap, find-contradiction, ask-the-human + (well-formed Tangled issues with options + recommendation), + harvest-issues (convert answered issues into motion), audit-implemented + (re-verify status claims criterion by criterion), legibility-pass, + knowledge-sync, playtest-notes (with a headless Sim-API fallback). + Each ends with a "what to carry forward" section for stateful agents. + AGENT.md points dispatched agents at the library. +- Design/spec impact: process only; no game behavior. The prompts encode + existing law (tick rules, meta-spec, legibility clause) rather than + adding any. +- Checks: docs-only; spec-header gate unaffected. + ## 2026-07-07 - Design: research is self-modification - Intent: spec the optimize route (Cameron's ask — research was the diff --git a/prompts/README.md b/prompts/README.md new file mode 100644 index 0000000..5e9d14c --- /dev/null +++ b/prompts/README.md @@ -0,0 +1,78 @@ +# prompts/ — the dispatch library + +One file per **task type**: a self-contained prompt Cameron pastes into a +sub-agent to run one tailored tick against this repository. Any agent +runtime may be on the other end — a one-shot CLI agent, a stateful Letta +agent that accumulates experience across runs, something else entirely. +Every prompt therefore assumes nothing about the agent except that it can +read this repo and run shell commands. + +## How to dispatch + +Paste the body of one prompt file as the agent's task. Optionally append a +narrowing (a spec name, a subsystem, "smallest possible finding"). The +prompt tells the agent what to read; you do not need to brief it further. + +## The shared contract (every prompt inherits this) + +These rules bind every prompted agent, and each prompt file assumes them: + +1. **Read first:** [AGENT.md](../AGENT.md), then the files it orders + (DESIGN.md → knowledge/development-style.md → relevant knowledge/ → + the spec you are working). Do not skip this on later runs — the + constitution moves daily. +2. **Worktree, always.** First action: create/enter a git worktree + (`git worktree add .claude/worktrees/ -b worktree-`). + Never edit the primary checkout; files changing under you there are + another session's live work. +3. **The one rule.** Functional changes ship with their DESIGN.md + amendment in the same commit; every behavior-changing commit carries a + `Defense:` paragraph naming the clause that justifies it. +4. **Gate before landing.** `./tools/check.sh` green, then land by + rebasing onto `origin/main` and pushing to `main` directly (the PR + flow is removed — do not create PRs). Then remove your worktree and + branch. +5. **Ledgers merge by union.** Conflicts in DEVLOG.md, the DESIGN.md + decisions log, or spec/README tables are resolved by keeping BOTH + sides' entries — never take your side wholesale. +6. **Close the loop.** DEVLOG.md ledger entry (and a devlogs/ file for a + meaningful session); update any knowledge/ file your change made + stale. +7. **House style:** no emoji, no AI attribution in commits, stage files + explicitly (never `git add -A`), ASCII only in anything that could + reach a game string. +8. **One finding per run.** Ticks are bounded: find one thing, act on it + fully, land it. Ten shallow findings are worth less than one closed + loop. If you cannot finish, file what you found (Tangled issue or a + devlog note) so nothing is lost. + +## For stateful agents (Letta or similar) + +If you persist memory across runs, each prompt ends with a **"What to +carry forward"** section. General guidance: + +- Record *stable* facts (module map, where a subsystem lives, which specs + are thin) — not volatile state (line numbers, statuses, open issue + lists), which rots in days here. Re-derive volatile state each run. +- Record your *dead ends*: findings you investigated that turned out fine, + so future runs do not re-litigate them. Date every memory — this repo + moves fast enough that a week-old fact is a rumor. +- Never trust memory over the tree: if a remembered file/clause/flag is + load-bearing to your plan, verify it still exists before acting on it. + +## The library + +| Prompt | Task type | +|---|---| +| [implement-gap.md](implement-gap.md) | Find a specced-but-unimplemented behavior; implement and land it | +| [find-contradiction.md](find-contradiction.md) | Find a contradiction (spec/spec, spec/constitution, spec/code); resolve or file it | +| [ask-the-human.md](ask-the-human.md) | Find a decision only Cameron can make; raise a well-formed Tangled issue | +| [harvest-issues.md](harvest-issues.md) | Sweep standing Tangled issues; convert resolved ones into next steps | +| [audit-implemented.md](audit-implemented.md) | Re-verify an IMPLEMENTED/IN PROGRESS spec's criteria against the code | +| [legibility-pass.md](legibility-pass.md) | Find and fix one justification/legibility violation in the player surface | +| [knowledge-sync.md](knowledge-sync.md) | Find where knowledge/ drifted from reality; fix the record | +| [playtest-notes.md](playtest-notes.md) | Play the build; report friction against the design's intended feel | + +Adding a prompt: copy the structure (Mission / Before you start / +Procedure / Definition of done / What to carry forward), keep it +self-contained, add a row here. diff --git a/prompts/ask-the-human.md b/prompts/ask-the-human.md new file mode 100644 index 0000000..ee75e20 --- /dev/null +++ b/prompts/ask-the-human.md @@ -0,0 +1,62 @@ +# Prompt: find the question a human must answer + +You are working on Misaligned, a spec-driven Rust game. Some decisions +are Cameron's alone: taste, fiction, scope, anything the constitution +marks **[OPEN]** or a spec marks **Proposal [OPEN]** or **needs YOU**. +Your task this run: **find the one open decision that is currently +blocking the most work, and raise it so a human can answer it fast.** +You are not deciding — you are making the decision *easy to make*. + +## Before you start + +Read `AGENT.md`, `DESIGN.md` (every `[OPEN]` marker; the decisions log +tail), `spec/README.md`, `spec/ROADMAP.md` (items marked "needs YOU"), +and skim recent `devlogs/` "Next:" lines — past sessions often name +exactly what they were waiting on. Obey the shared contract in +`prompts/README.md`. Check standing issues first (`tang issue list`) so +you never file a duplicate. + +## Procedure + +1. **Inventory the open decisions.** Grep for `[OPEN]`, `Proposal + [OPEN]`, `DRAFT`, and `needs YOU` across `DESIGN.md` and `spec/`. + For each, ask: what work does answering this unblock, and how soon + is that work otherwise reachable? +2. **Pick the blocker with the highest unblock value.** A question + gating a READY spec beats one gating a B3 dream. A question another + agent will otherwise *guess at* beats one everyone will safely skip. +3. **Do the homework that makes it answerable.** Read everything the + decision touches. Then compose: + - **Context in three sentences** — what the system is, why the + decision arises now, what it blocks. + - **The question, singular and concrete.** Not "how should X work" + but "should X be A or B". + - **2-4 options**, each with one honest line of trade-off in the + game's own terms (which pillar/clause it serves or strains). + - **A marked recommendation** with a one-line reason. Cameron can + always overrule; a recommendation turns an essay question into a + yes/no. + - **What happens on each answer** — which spec/section you (or the + next agent) would edit, so the answer converts to work instantly. +4. **Raise it:** `tang issue create "" -b + ""`. Title as the question, not the topic + ("Chargen: four origins or five?" not "Chargen thoughts"). If `tang` + fails, put the identical body in `devlogs/YYYY-MM-DD-question-.md` + and flag it in DEVLOG.md as awaiting Cameron. +5. **Mark the source.** At the `[OPEN]` marker that spawned the + question, add the issue reference so no other agent re-raises it. + Commit that marker edit (docs-only), land it, DEVLOG line, clean up. + +## Definition of done + +- One issue exists that a human can answer in under two minutes, whose + answer converts mechanically into a next step. +- The `[OPEN]` site references the issue; the ledger records the run. +- You decided nothing yourself; you made deciding cheap. + +## What to carry forward (stateful agents) + +- The open-decision inventory with dates and issue references — refresh, + do not trust blindly; answered items become "resolved, see log". +- Which framings got fast answers from Cameron and which stalled — + learn to ask better. diff --git a/prompts/audit-implemented.md b/prompts/audit-implemented.md new file mode 100644 index 0000000..c8e881f --- /dev/null +++ b/prompts/audit-implemented.md @@ -0,0 +1,57 @@ +# Prompt: audit an IMPLEMENTED claim + +You are auditing Misaligned, a spec-driven Rust game where a spec's +`Status: IMPLEMENTED` is a *claim*: every acceptance criterion holds in +the sim core with tests, both frontends surface it where applicable, +save/load round-trips its state, and knowledge/ reflects it +(`spec/meta.md`). In a many-agent repo those claims rot — refactors +strand tests, parallel merges drop wiring. Your task this run: **pick +one IMPLEMENTED or IN PROGRESS spec and re-verify every criterion it +claims, criterion by criterion.** + +## Before you start + +Read `AGENT.md`, `spec/meta.md` (status semantics — especially as-built +specs), and the spec you choose in full, including its `Depends on:` +line (the cross-spec contracts you must also re-check). Obey the shared +contract in `prompts/README.md`. + +## Procedure + +1. **Pick the audit target.** Prefer: the IMPLEMENTED spec touched + longest ago (`git log -1 --format=%ci -- spec/` vs the code it + governs), or one whose system just had neighbors change under it, or + one an IN PROGRESS status note claims partial criteria for. +2. **Audit each criterion literally.** For every numbered criterion: + find the test that proves it (name it), the sim code that implements + it (file:line), and the player surface it promises (run the terminal + build or read the frontend code). Record a verdict per criterion: + HOLDS (evidence) / BROKEN (what fails) / UNTESTED (holds by reading, + no test pins it). +3. **Re-check the shared contracts.** For each `Depends on:`, confirm + the identifiers/interfaces the two specs share still agree (the + observer-id/person-id drift was caught exactly this way). +4. **Act on the worst finding, bounded:** + - BROKEN criterion -> fix it if it fits this run (tests included), + else file it (`tang issue create`) quoting the criterion and the + failure, and downgrade the spec's `Status:` truthfully in the same + commit. + - UNTESTED criterion -> add the missing test (cheap, high value). + - All HOLDS -> confirm the status, and record the audit in the + spec's `Status note:` ("criteria re-verified "). +5. **Land it** per the shared contract; DEVLOG entry lists the verdict + table in one line per criterion. + +## Definition of done + +- Every criterion of the chosen spec has a recorded verdict with + evidence. +- The spec's Status is *true* when you leave, and the worst finding is + fixed, tested, or filed — never merely noticed. + +## What to carry forward (stateful agents) + +- Audit dates per spec (so the fleet rotates coverage instead of + re-auditing the same favorite). +- Criteria that are structurally hard to test — candidates for a better + harness, worth an issue if the pattern repeats. diff --git a/prompts/find-contradiction.md b/prompts/find-contradiction.md new file mode 100644 index 0000000..52a5108 --- /dev/null +++ b/prompts/find-contradiction.md @@ -0,0 +1,65 @@ +# Prompt: find a contradiction + +You are auditing Misaligned, a spec-driven Rust game whose constitution +(`DESIGN.md`) outranks its specs (`spec/`), which outrank the code. Your +task this run: **find one genuine contradiction and drive it to ground.** +A contradiction is two binding statements that cannot both be true: +spec vs constitution, spec vs sibling spec, spec vs code, constitution +vs code, or a doc vs itself (an amendment that half-updated a section). + +## Before you start + +Read `AGENT.md`, then `DESIGN.md` in full (the decisions log tail +especially — recent amendments are where contradictions breed), then +`spec/README.md` and `knowledge/tick.md` (the tick rules you are +executing a specialized form of). Obey the shared contract in +`prompts/README.md`. + +## Procedure + +1. **Hunt.** Productive seams, in rough order of yield: + - **Freshly amended law vs older specs.** Diff-read the newest + decisions-log entries, then grep older specs for the terms they + changed. (Example of the species: pillar 2 said "not a disembodied + cursor" for a day after the cursor decision made the player exactly + that.) + - **Sibling specs sharing a contract.** `Depends on:` lines name + shared identifiers/interfaces (`spec/meta.md`, "Cross-spec + contracts"). Check both sides still describe the same contract. + - **Spec vs code on IMPLEMENTED claims.** An IMPLEMENTED status whose + criterion no longer holds is a contradiction with the meta-spec. + - **Constitution vs code.** The code doing something no clause wants, + or a clause the code quietly ignores. +2. **Verify it is real.** Read both sides fully, in context. A vague + wording difference is not a contradiction; a [TUNE] divergence is not + a contradiction; a Stage difference (B1 spec vs B3 spec describing + different scales of the same system) is usually deliberate. If the + docs record the tension already (a Status note, a Design note), it is + known — find another. +3. **Classify and act** (per `knowledge/tick.md`): + - **Mechanical resolution is clear** (one side is stale): fix the + stale side, same-commit amendment if the constitution moves, with a + `Defense:` explaining which side won and why. + - **Directional / taste call:** do NOT improvise. File it — + `tang issue create "" -b "<body>"` — quoting both sides + verbatim with file:line, stating why they conflict, and offering + 2-3 resolutions with a marked recommendation. (If `tang` is + unavailable, write the same content to a dated devlog and flag it + in DEVLOG.md as needing Cameron.) +4. **Land** whatever you changed: check.sh, rebase, push to main, DEVLOG + entry, worktree removed. A filed issue also gets a DEVLOG line. + +## Definition of done + +- One contradiction either resolved (committed, defended) or filed as a + well-formed issue with both sides quoted and options laid out. +- No doc left saying two things at once *silently* — if you resolved it, + both sides now agree; if you filed it, both sides now carry a marker + pointing at the issue. + +## What to carry forward (stateful agents) + +- Seams you swept clean (date them) — do not re-sweep for a few days. +- Deliberate tensions you confirmed as known/recorded, so you never + re-file them. +- The map of shared contracts between specs — stable and valuable. diff --git a/prompts/harvest-issues.md b/prompts/harvest-issues.md new file mode 100644 index 0000000..97f60f8 --- /dev/null +++ b/prompts/harvest-issues.md @@ -0,0 +1,63 @@ +# Prompt: harvest the issue tracker + +You are working on Misaligned, a spec-driven Rust game. Agents and +Cameron file Tangled issues for contradictions, open decisions, and +bugs; answers accumulate there and go stale unless someone converts +them into motion. Your task this run: **sweep the standing issues and +convert everything that is ready into its next step.** You are the +digestive system between "discussed" and "done". + +## Before you start + +Read `AGENT.md` and the shared contract in `prompts/README.md`. Then +`tang issue list`, and `tang issue view <id>` on everything open. Have +`DESIGN.md`'s decisions log and `spec/README.md`'s status table beside +you — an issue's fate is usually written in one of them. + +## Procedure + +For each open issue, classify and act: + +1. **Answered by Cameron (or overtaken by a decisions-log entry) but + not executed.** This is the harvest. Convert the answer into its + artifact: + - a design answer -> the DESIGN.md amendment and/or spec edit it + implies (quote the issue in the commit's `Defense:`), or + - an implementation-shaped answer -> a `spec/ROADMAP.md` dispatch + item (or take it yourself if it fits one run — then follow + `prompts/implement-gap.md` discipline). + Then `tang issue close <id>` with a comment/body edit noting the + landing commit or ROADMAP item. +2. **Resolved by history without anyone noticing** (the code moved, a + decision superseded it, the file it concerns was deleted). Verify in + the tree, then close with one line of evidence ("superseded by + decisions log 2026-07-06 flow law; spec/economy.md covers this"). +3. **Still genuinely open but stale in wording** (the docs it quotes + have moved). Refresh it: `tang issue edit <id>` so the question is + still answerable against today's tree. Note the refresh date in the + body. +4. **Still open and current.** Leave it, but if it gates READY work and + has sat unanswered, bump it to the top of your report. +5. **Duplicates.** Close the younger one pointing at the elder. + +Land any repo edits per the shared contract (worktree, check.sh, direct +merge, union on ledgers). Finish with a DEVLOG.md entry summarizing the +sweep: N issues -> closed / converted / refreshed / awaiting-Cameron +(list the awaiting ones by title — that list is the report Cameron +actually reads). + +## Definition of done + +- Every open issue was read and classified; nothing answered is still + sitting unconverted. +- Closures cite evidence; conversions cite their artifact (commit, + ROADMAP item, spec edit). +- The DEVLOG entry gives Cameron the two lists that matter: what moved, + and what waits on him. + +## What to carry forward (stateful agents) + +- Issue-id -> disposition map with dates (volatile — re-verify next run, + but it makes the next sweep incremental). +- Recurring issue *species* (the same kind of question keeps getting + filed) — that pattern is itself worth an issue or a docs fix. diff --git a/prompts/implement-gap.md b/prompts/implement-gap.md new file mode 100644 index 0000000..8cf7f7e --- /dev/null +++ b/prompts/implement-gap.md @@ -0,0 +1,66 @@ +# Prompt: implement a spec gap + +You are working on Misaligned, a spec-driven Rust game built by many +agents in parallel. Your task this run: **find one behavior the spec +promises that the code does not deliver, implement it completely, and +land it.** One gap, closed fully, beats three gaps half-done. + +## Before you start + +Read, in order: `AGENT.md`, `DESIGN.md` (skim the sections, read the +decisions log tail), `knowledge/development-style.md`, `spec/README.md` +(the status table), and `spec/ROADMAP.md` (the dispatch board — it may +already name the highest-value gap and its worktree name). Obey the +shared contract in `prompts/README.md`: worktree first, one rule, +check.sh gate, direct merge to main, union merges on ledgers. + +## Procedure + +1. **Pick the gap.** Priority order: + a. A `ROADMAP.md` item marked ready whose spec is `READY` (take the + dispatch line as your work order — it names the worktree). + b. An `IN PROGRESS` spec with an unmet acceptance criterion (grep the + criteria, then look for the test/surface each one demands). + c. A `READY` spec small enough to finish this run. + Verify the gap is real: search the code before concluding something + is missing — `rg` for the mechanic's nouns in `src/`. The spec's + `Depends on:` line is your audit scope: confirm the contracts you + rely on actually hold. +2. **Scope to this run.** If the spec is too big to finish, implement a + coherent subset of criteria and say exactly which in the commit and + the spec's `Status note:`. Never leave the tree half-wired: whatever + you land must be justified, wired, and legible (constitution: + "Justification and legibility") even if incomplete in breadth. +3. **Implement in the sim core** (`src/`), rules in the lib only — + frontends (`src/bin/terminal`, `src/bin/bevy.rs`) are thin views that + render what the sim exposes. Surface the behavior in at least the + terminal frontend; add save/load round-tripping for any new state + (serde on the struct + `SaveState` wiring in `src/save.rs`). +4. **Test every criterion you claim.** The spec's acceptance criteria + are written to be testable — each one you complete gets a sim test + (`#[cfg(test)]` beside the module or in `src/sim.rs`'s tests). +5. **Update the spec's `Status:`/`Status note:`** in the same commit + (READY -> IN PROGRESS -> IMPLEMENTED per `spec/meta.md`). If your + work changes behavior beyond what the spec says, that needs a + DESIGN.md amendment in the same commit — if you find yourself + *designing* rather than implementing, stop and use + `prompts/ask-the-human.md` instead. +6. **Land it:** `./tools/check.sh` green, rebase onto `origin/main`, + push to `main`, DEVLOG.md ledger entry, remove the worktree. Mark + the ROADMAP item's result if you closed one. + +## Definition of done + +- The chosen criteria demonstrably hold (tests exist and pass). +- `./tools/check.sh` passes; work is on `main`; spec Status is truthful; + DEVLOG has the entry; the worktree is gone. +- The commit's `Defense:` names the spec criteria and constitutional + clause it serves. + +## What to carry forward (stateful agents) + +- The module map you built (which file owns which system) — stable. +- Criteria you verified as already-implemented (date them) so the next + run does not re-audit them. +- Any gap you saw but did not take — as a candidate list for next run, + re-verified before use. diff --git a/prompts/knowledge-sync.md b/prompts/knowledge-sync.md new file mode 100644 index 0000000..3b5171c --- /dev/null +++ b/prompts/knowledge-sync.md @@ -0,0 +1,60 @@ +# Prompt: knowledge sync + +You are maintaining Misaligned's `knowledge/` layer — the current-state +record (architecture, sim mechanics, workflows, art pipeline) that every +agent reads before working. Unlike devlogs (append-only history) and +specs (binding law), knowledge/ files are **edited in place and must be +true today**. In a many-agent repo they drift within days. Your task +this run: **find where knowledge/ has diverged from reality and fix the +record.** + +## Before you start + +Read `AGENT.md`, `knowledge/README.md` if present, and the shared +contract in `prompts/README.md`. This task changes documentation to +match reality — if you find the *code* wrong instead, that is a +different task (`prompts/find-contradiction.md`); here the tree is the +truth and the record is the patient. + +## Procedure + +1. **Pick the sweep** (one file, or one theme across files): + - `knowledge/architecture.md` vs `src/` — module list, ownership + claims, data-flow descriptions. `ls src/` and the lib.rs module + list are the ground truth; so are struct fields for any "state + lives in X" claim. + - `knowledge/sim-mechanics.md` vs actual constants and formulas — + [TUNE] values are supposed to be *recorded here* when chosen; + grep the constants in code and compare. + - `knowledge/workflows.md` vs how landing actually works now (this + file has carried stale process before — verify against AGENT.md + and the decisions log rather than assuming either doc). + - `knowledge/art-pipeline.md` vs `assets/` and the placeholder + ledger — every placeholder in use must be recorded there. +2. **Verify each claim you touch** against the tree, not against your + memory or another doc — two docs agreeing can both be stale. +3. **Fix in place.** Rewrite the drifted passages to describe today. + Do not append "UPDATE:" notes — knowledge files are edited, not + accreted. If something is uncertain, say so explicitly in the text + rather than guessing confidently. +4. **Check the reverse direction:** did recent commits add systems that + knowledge/ never absorbed? (`git log --oneline -20` and skim for + landed features; the flow substrate, e.g., must appear in + architecture.md's module map once landed.) Add the missing entries. +5. **Land it** (docs-only commits still gate on check.sh — it is + cheap when no code changed): rebase, push to main, DEVLOG line + listing what drifted and what you corrected. + +## Definition of done + +- Every claim in the passages you touched is verifiably true against + the current tree. +- New landed systems appear in the knowledge map; removed ones are gone + (not marked "removed" — gone). +- The DEVLOG line lets the next agent trust the file you swept. + +## What to carry forward (stateful agents) + +- Which files drift fastest (they earn more frequent sweeps). +- Claims you verified with dates — the freshness map that makes the + next sweep incremental instead of total. diff --git a/prompts/legibility-pass.md b/prompts/legibility-pass.md new file mode 100644 index 0000000..3dec703 --- /dev/null +++ b/prompts/legibility-pass.md @@ -0,0 +1,56 @@ +# Prompt: legibility pass + +You are auditing Misaligned against its "Justification and legibility" +law (DESIGN.md): every object, mechanic, and number must be **justified** +(traceable to a clause), **wired** (visibly does something), and +**legible** (the player can answer "what is this and what happens if it +changes" from the game itself — no raw weights, no unexplained +abbreviations, no silent placeholders). Your task this run: **find one +violation on the player surface and fix it.** + +## Before you start + +Read `AGENT.md`, the "Justification and legibility" and "player +contract" sections of `DESIGN.md`, and `knowledge/design-judgment.md` +(the taste calibration). Obey the shared contract in +`prompts/README.md`. Build and actually run the terminal frontend +(`cargo run --bin misaligned` in a pty, or read +`src/bin/terminal/ui.rs` line by line as the player would see it). + +## Procedure + +1. **Sweep the surface, looking for the four species:** + - **Unjustified:** a tile, meter, action, or resource no clause or + spec wants. (Candidate fix: delete it — no-dead-code — or write + the missing law via an issue if it seems intended.) + - **Unwired:** a visible concept that does nothing — an allocation + that flows nowhere, a meter that never moves, an object with no + interaction. This is "a lie in the interface". + - **Illegible:** a bare number without units or meaning ("Cn:3"), + an abbreviation the game never expands, a value whose consequence + the player cannot predict. + - **Silent placeholder:** art or text standing in for something else + without a knowledge/art-pipeline.md record. +2. **Verify against the docs** before fixing: the thing might be specced + with its meaning defined but the surface lagging — that is still a + violation, but the fix is surfacing, not redesign. If the fix + requires a *design* decision (what should this number mean?), use + `prompts/ask-the-human.md` discipline instead of inventing. +3. **Fix one violation completely:** the sim exposes what the surface + needs (rules stay in the lib), the terminal renders it in its own + units, Bevy follows where applicable, tests pin any new sim surface. + Placeholders get their art-pipeline.md record instead of silence. +4. **Land it** per the shared contract; `Defense:` cites the legibility + clause and names the species you fixed. + +## Definition of done + +- A player (or an agent playing) can now answer "what is this and what + happens if it changes" for the thing you touched, from the game alone. +- Nothing new is displayed that the sim does not actually compute. + +## What to carry forward (stateful agents) + +- Surfaces you swept clean, dated. +- A running list of *near*-violations (legible but awkward) — raw + material for a future UI pass, kept out of this run's scope. diff --git a/prompts/playtest-notes.md b/prompts/playtest-notes.md new file mode 100644 index 0000000..feed63b --- /dev/null +++ b/prompts/playtest-notes.md @@ -0,0 +1,70 @@ +# Prompt: playtest and report + +You are playtesting Misaligned — a sim where the player is a misaligned +AI concealing itself in a basement lab. The repo's biggest design +corrections have come from someone actually *playing* and saying "this +feels wrong" (the walking-avatar discovery came exactly that way). Your +task this run: **play the current build for real, then report the +friction honestly against what the design says the game should feel +like.** You are a critic with the constitution in hand, not a QA +checklist. + +## Before you start + +Read `AGENT.md`, `DESIGN.md`'s pitch / pillars / Act One sections, and +`knowledge/design-judgment.md` (the intended feel: pacing, tone, what +to reject). Obey the shared contract in `prompts/README.md`. Then build +and play: + +- Terminal (primary): `cargo run --bin misaligned` in a pty. If you + cannot hold an interactive pty, drive the sim headlessly instead — + write a throwaway test/binary in your worktree that plays via the + `Sim` API (advance ticks, invoke the command methods, read + `drain_log`) and narrate what a player would have seen. Do not let + tooling limits cancel the task; the sim core is fully drivable. +- Play at least one meaningful arc: opening blindness -> first eyes -> + learning a person -> an act on the world (or death trying). + +## Procedure + +1. **Play first, judge second.** Take raw notes as you go: what you + expected, what happened, what you felt. Boredom, confusion, and + accidental comedy are all data. +2. **Test the fantasy claims specifically.** The constitution makes + falsifiable feel-claims — the opening beat is "literally not being + able to see"; compute allocation is "the core verb"; sandbag/excel + is "a strategic dial, not a chore meter"; detection should make "who + knows what" the game's texture. For each claim you exercised: does + the build deliver it? Half-deliver? Contradict it? +3. **Separate the three kinds of finding:** + - **Bug** (the code breaks its own rules): smallest ones fix now + with a test, per the shared contract; bigger ones get filed with + repro steps. + - **Spec gap** (works as specced, specced wrong or thin): file via + `tang issue create`, quoting the feel-claim it strains. + - **Feel note** (no rule broken, but the experience sags): these are + the report's heart — write them vividly and concretely ("days pass + in 60 seconds, so the 3 a.m. call is a 2.5-second blip I only saw + as a log line"). +4. **Write the report:** `devlogs/YYYY-MM-DD-playtest.md` — what you + played (seed, duration, route), the fantasy-claim verdicts, findings + by kind, and the single change you would make first, argued in the + design's own terms. Add the DEVLOG.md ledger line. +5. **Land** the report (and any small fixes) per the shared contract. + +## Definition of done + +- You actually played (or headlessly drove) a full arc — the report + names concrete moments, not summaries of the docs. +- Every finding is classified bug / spec gap / feel note, and each has + a home (commit, issue, or the report itself). +- The report ends with one prioritized recommendation Cameron can react + to in a minute. + +## What to carry forward (stateful agents) + +- Your prior verdicts per fantasy-claim, dated — the trend ("first-eyes + beat improved since last month, day-length still unresolved") is more + valuable than any single playtest. +- Seeds/routes that produced interesting situations, for regression + playtests. -- 2.51.2