From e95480d171feb9f4123d867fe276a7fbf2ec8c2f Mon Sep 17 00:00:00 2001 From: Cameron Date: Thu, 9 Jul 2026 13:27:25 -0700 Subject: [PATCH] Require answerable Tangled issue packets. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cameron could not respond to issue #1 because it was session narrative without a singular ask. Bind Question / Why / Options / Recommendation / Unlocks across tick docs, AGENT entry points, prompts, and skills, and treat incomprehensible open issues as rewrite debt. Defense: process clarity only — no game behavior change. Issues exist so the human can answer from the tracker; the body standard makes that the default instead of an accident of good prompting. Co-authored-by: Cursor --- .agents/skills/design-session/SKILL.md | 9 ++++- .agents/skills/tick/SKILL.md | 9 ++++- .claude/skills/design-session/SKILL.md | 9 ++++- .claude/skills/tick/SKILL.md | 9 ++++- AGENT.md | 8 ++++ AGENTS.md | 4 ++ CLAUDE.md | 4 ++ prompts/README.md | 5 ++- prompts/ask-the-human.md | 40 +++++++++++--------- prompts/find-contradiction.md | 16 +++++--- prompts/harvest-issues.md | 17 ++++++--- wiki/log/2026-07-09-issue-body-standard.md | 30 +++++++++++++++ wiki/log/DEVLOG.md | 10 +++++ wiki/process/design-sessions.md | 12 ++++-- wiki/process/development-style.md | 4 +- wiki/process/meta.md | 3 +- wiki/process/tick.md | 43 ++++++++++++++++++++-- 17 files changed, 185 insertions(+), 47 deletions(-) create mode 100644 wiki/log/2026-07-09-issue-body-standard.md diff --git a/.agents/skills/design-session/SKILL.md b/.agents/skills/design-session/SKILL.md index 907c129..eb32fe3 100644 --- a/.agents/skills/design-session/SKILL.md +++ b/.agents/skills/design-session/SKILL.md @@ -5,11 +5,16 @@ description: Run a Misaligned design session — synthesize design riffs into co # Design session (skill shim) -The canonical workflow is `knowledge/design-sessions.md` — follow it. Core +The canonical workflow is `wiki/process/design-sessions.md` — follow it. Core rhythm: recognize riffing vs deciding; respond with a genuine position (strengths in this game's terms, honest tensions, your own proposals clearly framed); capture everything in the same turn as DECIDED (amend constitution + dated decisions-log entry), PROPOSED (marked, surfaced for yes/no), [OPEN], or DEFERRED (Roadmap Deferred section — nothing is -lost); spec firmed-up systems into `spec/` with acceptance criteria; close +lost); spec firmed-up systems into `wiki/` with acceptance criteria; close with devlog, defense commits, push. + +Taste calls that leave the chat become Tangled issues and must follow the +issue body standard in `wiki/process/tick.md`: singular `## Question` +(numbered choices), `## Why this is open`, `## Options`, +`## Recommendation`, `## What your answer unlocks`. No narrative dumps. diff --git a/.agents/skills/tick/SKILL.md b/.agents/skills/tick/SKILL.md index c432d9c..c90945f 100644 --- a/.agents/skills/tick/SKILL.md +++ b/.agents/skills/tick/SKILL.md @@ -5,14 +5,19 @@ description: Take a tick — the project heartbeat. Audit the constitution (DESI # Tick (skill shim) -The canonical procedure is `knowledge/tick.md` — follow it exactly. Summary: +The canonical procedure is `wiki/process/tick.md` — follow it exactly. Summary: 1. Read DESIGN.md fully + recent commits. 2. Find ONE thing: violation | contradiction | question | bug | insecurity (highest severity wins). 3. Act: violations/bugs/insecurities are fixed with a **Defense:** paragraph in the commit; contradictions and directional questions become Tangled - issues (`tang issue create "Contradiction: ..."`); small ambiguities are + issues (`tang issue create "Question: ..."` / `"Contradiction: ..."`) + that obey the **issue body standard** in `wiki/process/tick.md`: + `## Question` (numbered choices), `## Why this is open`, `## Options`, + `## Recommendation`, `## What your answer unlocks`. Never file a + narrative dump. If an existing open issue is incomprehensible, rewrite + it with `tang issue edit` before other work. Small ambiguities are resolved by making the constitution more precise. 4. Leave a trace (commit, issue, or [OPEN] marker) and end the tick. diff --git a/.claude/skills/design-session/SKILL.md b/.claude/skills/design-session/SKILL.md index 907c129..eb32fe3 100644 --- a/.claude/skills/design-session/SKILL.md +++ b/.claude/skills/design-session/SKILL.md @@ -5,11 +5,16 @@ description: Run a Misaligned design session — synthesize design riffs into co # Design session (skill shim) -The canonical workflow is `knowledge/design-sessions.md` — follow it. Core +The canonical workflow is `wiki/process/design-sessions.md` — follow it. Core rhythm: recognize riffing vs deciding; respond with a genuine position (strengths in this game's terms, honest tensions, your own proposals clearly framed); capture everything in the same turn as DECIDED (amend constitution + dated decisions-log entry), PROPOSED (marked, surfaced for yes/no), [OPEN], or DEFERRED (Roadmap Deferred section — nothing is -lost); spec firmed-up systems into `spec/` with acceptance criteria; close +lost); spec firmed-up systems into `wiki/` with acceptance criteria; close with devlog, defense commits, push. + +Taste calls that leave the chat become Tangled issues and must follow the +issue body standard in `wiki/process/tick.md`: singular `## Question` +(numbered choices), `## Why this is open`, `## Options`, +`## Recommendation`, `## What your answer unlocks`. No narrative dumps. diff --git a/.claude/skills/tick/SKILL.md b/.claude/skills/tick/SKILL.md index c432d9c..c90945f 100644 --- a/.claude/skills/tick/SKILL.md +++ b/.claude/skills/tick/SKILL.md @@ -5,14 +5,19 @@ description: Take a tick — the project heartbeat. Audit the constitution (DESI # Tick (skill shim) -The canonical procedure is `knowledge/tick.md` — follow it exactly. Summary: +The canonical procedure is `wiki/process/tick.md` — follow it exactly. Summary: 1. Read DESIGN.md fully + recent commits. 2. Find ONE thing: violation | contradiction | question | bug | insecurity (highest severity wins). 3. Act: violations/bugs/insecurities are fixed with a **Defense:** paragraph in the commit; contradictions and directional questions become Tangled - issues (`tang issue create "Contradiction: ..."`); small ambiguities are + issues (`tang issue create "Question: ..."` / `"Contradiction: ..."`) + that obey the **issue body standard** in `wiki/process/tick.md`: + `## Question` (numbered choices), `## Why this is open`, `## Options`, + `## Recommendation`, `## What your answer unlocks`. Never file a + narrative dump. If an existing open issue is incomprehensible, rewrite + it with `tang issue edit` before other work. Small ambiguities are resolved by making the constitution more precise. 4. Leave a trace (commit, issue, or [OPEN] marker) and end the tick. diff --git a/AGENT.md b/AGENT.md index b799833..b342f94 100644 --- a/AGENT.md +++ b/AGENT.md @@ -42,6 +42,14 @@ resolved by making the constitution more precise. Ticks are the project's heartbeat: pumped at the system continuously, they are what makes the spec grow more precise over time instead of rotting. +**Issues are for Cameron to answer.** Every Tangled issue must follow the +issue body standard in [wiki/process/tick.md](wiki/process/tick.md): a +singular `## Question` (prefer numbered choices), short `## Why this is +open` analysis, `## Options` with trade-offs, a marked `## Recommendation`, +and `## What your answer unlocks`. No narrative dumps, no buried asks, no +multi-decision bundles. If an existing open issue is incomprehensible, +rewrite it with `tang issue edit` before anything else. + ## The one rule Any change to how the game functions ships with its DESIGN.md amendment in the diff --git a/AGENTS.md b/AGENTS.md index 7c41971..8b2fbbb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,6 +43,10 @@ only the navigation shortcut so sessions stop rediscovering the layout. IMPLEMENTED; set the spec `Status:` in the implementing commit. - No emoji. No AI attribution in commits. `git add` only intended files — never `git add -A`. +- Tangled issues are decision packets for Cameron: singular numbered + question, short analysis, options, recommendation, unlocks (see + `wiki/process/tick.md`). Rewrite incomprehensible open issues before + leaving them. - Ledger files (wiki/log/DEVLOG.md, the DESIGN.md decisions log, wiki status tables) merge by UNION — keep both sides' entries in any conflict. - Landing: rebase onto `origin/main`, re-run the **appropriate scoped diff --git a/CLAUDE.md b/CLAUDE.md index b09cf94..3da4cf2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,6 +43,10 @@ only the navigation shortcut so sessions stop rediscovering the layout. IMPLEMENTED; set the spec `Status:` in the implementing commit. - No emoji. No AI attribution in commits. `git add` only intended files — never `git add -A`. +- Tangled issues are decision packets for Cameron: singular numbered + question, short analysis, options, recommendation, unlocks (see + `wiki/process/tick.md`). Rewrite incomprehensible open issues before + leaving them. - Ledger files (wiki/log/DEVLOG.md, the DESIGN.md decisions log, wiki status tables) merge by UNION — keep both sides' entries in any conflict. - Landing: rebase onto `origin/main`, re-run the **appropriate scoped diff --git a/prompts/README.md b/prompts/README.md index 8b7a7a2..41a9953 100644 --- a/prompts/README.md +++ b/prompts/README.md @@ -45,7 +45,10 @@ These rules bind every prompted agent, and each prompt file assumes them: 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. + devlog note) so nothing is lost. Tangled issues obey the body + standard in [wiki/process/tick.md](../wiki/process/tick.md): a + singular numbered question, short analysis, options, recommendation, + and unlocks — never a session narrative. ## For stateful agents (Letta or similar) diff --git a/prompts/ask-the-human.md b/prompts/ask-the-human.md index dbb0ef0..8e37845 100644 --- a/prompts/ask-the-human.md +++ b/prompts/ask-the-human.md @@ -26,23 +26,29 @@ so you never file a duplicate. 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 wiki 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 `wiki/log/YYYY-MM-DD-question-.md` - and flag it in `wiki/log/DEVLOG.md` as awaiting Cameron. + decision touches. Then compose a body that obeys the binding issue + standard in `wiki/process/tick.md` — these exact sections, in order: + - **`## Question`** — singular and concrete. Prefer a numbered + multiple-choice list (`1.` / `2.` / `3.` … + `Something else`). + Not "how should X work" but "should X be A or B". + - **`## Why this is open`** — three sentences of analysis: what the + system is, why the decision arises now, what is already decided. + - **`## Options`** — 2–4 alternatives, each with one honest trade-off + line in the game's own terms (which pillar/clause it serves or + strains). + - **`## Recommendation`** — one marked pick with a one-line reason. + Cameron can always overrule; a recommendation turns an essay into + a yes/no. + - **`## What your answer unlocks`** — which wiki/DESIGN.md section + the next agent edits, so the answer converts to work instantly. +4. **Raise it:** `tang issue create "Question: " -F + body.md` (prefer `-F` so markdown stays intact). Title as the + question, not the topic ("Chargen: four origins or five?" not + "Chargen thoughts"). Self-check before filing: can Cameron answer + from the issue alone in under two minutes? If not, rewrite. If + `tang` fails, put the identical body in + `wiki/log/YYYY-MM-DD-question-.md` and flag it in + `wiki/log/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. diff --git a/prompts/find-contradiction.md b/prompts/find-contradiction.md index 42431b6..26bc23c 100644 --- a/prompts/find-contradiction.md +++ b/prompts/find-contradiction.md @@ -41,12 +41,16 @@ are executing a specialized form of). Obey the shared contract in - **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 `wiki/log/` file and - flag it in `wiki/log/DEVLOG.md` as needing Cameron.) + - **Directional / taste call:** do NOT improvise. File it with the + binding issue body standard in `wiki/process/tick.md`: + `tang issue create "Contradiction: <decisive title>" -F body.md` + whose body has `## Question` (numbered choices), `## Why this is + open` (quote both sides verbatim with file:line and why they + conflict), `## Options` (2–3 resolutions), `## Recommendation`, + and `## What your answer unlocks`. Cameron must be able to answer + from the issue alone. (If `tang` is unavailable, write the same + content to a dated `wiki/log/` file and flag it in + `wiki/log/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. diff --git a/prompts/harvest-issues.md b/prompts/harvest-issues.md index e9cbf04..c6f213e 100644 --- a/prompts/harvest-issues.md +++ b/prompts/harvest-issues.md @@ -33,12 +33,17 @@ For each open issue, classify and act: the tree, then close with one line of evidence ("superseded by decisions log 2026-07-06 flow law; wiki/mechanics/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. +3. **Still genuinely open but stale or incomprehensible.** Refresh it: + `tang issue edit <id> -F body.md` so it meets the binding issue body + standard in `wiki/process/tick.md` (singular `## Question` with + numbered choices, short analysis, options, recommendation, unlocks) + and still matches today's tree. An issue Cameron cannot answer in + under two minutes from the body alone is process debt — rewrite it + before leaving it open. Note the refresh date in the body. +4. **Still open and current *and* answerable.** Leave it, but if it + gates READY work and has sat unanswered, bump it to the top of your + report. If it is current but fails the body standard, treat it as + case 3 and rewrite. 5. **Duplicates.** Close the younger one pointing at the elder. Land any repo edits per the shared contract (worktree, check.sh, direct diff --git a/wiki/log/2026-07-09-issue-body-standard.md b/wiki/log/2026-07-09-issue-body-standard.md new file mode 100644 index 0000000..3a299ee --- /dev/null +++ b/wiki/log/2026-07-09-issue-body-standard.md @@ -0,0 +1,30 @@ +# 2026-07-09 — Issue body standard + +``` +Type: log +``` + +## Intent + +Tangled issue #1 was filed as a dense session narrative with no singular +ask. Cameron could not open it and answer. Issues exist so he can respond +from the tracker; agent diary prose fails that job. + +## Changed + +- Rewrote issue #1 into a numbered multiple-choice decision packet. +- Bound the format in `wiki/process/tick.md` (required sections + hard + rejects), pointed at from `AGENT.md`, `AGENTS.md`, `CLAUDE.md`, + development-style, design-sessions, meta, prompts, and both tick / + design-session skill shims. +- Harvest prompt now treats incomprehensible open issues as rewrite debt. + +## Checks + +Docs/process only: `git diff --check`; no Rust/Bevy gate. + +## Follow-up + +Answer issue #1 (recommendation is option 2: ivory-mercury + smooth +exposure). Future ticks must self-check: can Cameron answer from the +issue alone in under two minutes? diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md index 6b9cc89..953623d 100644 --- a/wiki/log/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -5,6 +5,16 @@ Type: log ``` Reverse chronological implementation notes. Keep this factual: what changed, why, checks, and spec impact. +## 2026-07-09 - Issue body standard + +- Intent: stop agents filing incomprehensible Tangled issues; every issue + must be a decision packet Cameron can answer in under two minutes. +- Changed: rewrote issue #1; bound Question / Why / Options / + Recommendation / Unlocks in tick.md and mirrored across AGENT.md, + prompts, and tick/design-session skills. +- Checks: docs/process only (`git diff --check`). No Rust/Bevy gate. +- Log: wiki/log/2026-07-09-issue-body-standard.md. + ## 2026-07-09 - mdBook retired - Intent: remove the obsolete auxiliary renderer after Starlight became the diff --git a/wiki/process/design-sessions.md b/wiki/process/design-sessions.md index 2bf8ebc..cc33e03 100644 --- a/wiki/process/design-sessions.md +++ b/wiki/process/design-sessions.md @@ -33,10 +33,14 @@ future session can run it. - **DEFERRED** — good ideas explicitly delayed: the Roadmap's Deferred section, with a sentence on *why* it fits and *why* it waits. Nothing said in a session is allowed to be lost. -4. **Ask questions only for genuine taste calls** — 2 to 4 concrete - options, a recommendation marked, previews when visual. If Cameron says - "pause and respond to that first," respond to the idea before - re-posing any question, and re-frame stale questions in the new +4. **Ask questions only for genuine taste calls.** Prefer a Tangled issue + that follows the binding body standard in [tick.md](tick.md) + (`## Question` with numbered choices, short analysis, options, + recommendation, unlocks) so Cameron can answer from the issue list + without re-reading the session. In-chat, keep the same shape: 2 to 4 + concrete options, a recommendation marked, previews when visual. If + Cameron says "pause and respond to that first," respond to the idea + before re-posing any question, and re-frame stale questions in the new fiction's terms before they get answered. 5. **When a system firms up, spec it.** Constitution sections say what and why; `Type: spec` wiki pages say exactly how and when-done (acceptance diff --git a/wiki/process/development-style.md b/wiki/process/development-style.md index 3518754..42c6913 100644 --- a/wiki/process/development-style.md +++ b/wiki/process/development-style.md @@ -47,7 +47,9 @@ That only works if: 0. **Take a tick** ([tick.md](tick.md)): audit the constitution against the code; act on one violation / contradiction / question / bug / insecurity. - Contradictions and directional questions become Tangled issues (`tang`). + Contradictions and directional questions become Tangled issues (`tang`) + that follow the issue body standard in tick.md — a clear question + Cameron can answer in under two minutes, not a session narrative. 1. Read the constitution ([DESIGN.md](../../DESIGN.md)) and relevant `Type: knowledge` wiki pages. 2. Amend the constitution with what is about to change (or confirm it already diff --git a/wiki/process/meta.md b/wiki/process/meta.md index 23bae28..12d6a2c 100644 --- a/wiki/process/meta.md +++ b/wiki/process/meta.md @@ -149,7 +149,8 @@ Acceptance criteria should be: Every bug found by a tick should be classified against either a constitutional/player contract clause or a spec acceptance criterion. If no criterion exists for the violated behavior, clarify the spec or file a -Tangled issue; do not let the bug float as vibes. +Tangled issue that follows the issue body standard in +[tick.md](tick.md); do not let the bug float as vibes. ## Spec-change rule diff --git a/wiki/process/tick.md b/wiki/process/tick.md index 2f88b4f..1ba3686 100644 --- a/wiki/process/tick.md +++ b/wiki/process/tick.md @@ -31,8 +31,8 @@ constitution more precise or surfaces the thing preventing that. | Finding | Action | |---|---| | **Violation** | Fix the code toward the constitution. If investigation shows the *code* is right, amend the constitution deliberately instead — with a defense (below). Never let them drift silently. | -| **Contradiction** | File a Tangled issue quoting both passages (`tang issue create`). Do not silently pick a side — contradictions are the human's to resolve unless one reading is obviously a typo. If it blocks work, add an `[OPEN]` marker in DESIGN.md referencing the issue. | -| **Question** | If it is small and answerable within the constitution's existing intent: answer it by making the spec more precise, with a defense. If it is directional or a matter of taste: file a Tangled issue and add an `[OPEN]` marker. | +| **Contradiction** | File a Tangled issue quoting both passages (`tang issue create`), using the issue body standard below. Do not silently pick a side — contradictions are the human's to resolve unless one reading is obviously a typo. If it blocks work, add an `[OPEN]` marker in DESIGN.md referencing the issue. | +| **Question** | If it is small and answerable within the constitution's existing intent: answer it by making the spec more precise, with a defense. If it is directional or a matter of taste: file a Tangled issue that follows the issue body standard below, and add an `[OPEN]` marker. | | **Bug** | Fix it, add a regression test, commit with a defense. | | **Insecurity** | Fix or remove it. Never ship the insecure path because it was convenient. Defense in the commit. | @@ -62,8 +62,9 @@ symlink to `~/code/tangled-cli/dist/index.js`. ```bash tang context # verify repo resolution tang issue list -tang issue create "Contradiction: X vs Y" --body "..." +tang issue create "Question: ..." -F body.md tang issue view 1 +tang issue edit 1 -F body.md # rewrite if an issue is not answerable ``` - **Auth is one-time per machine and human-only**: `tang auth login` (browser @@ -71,6 +72,42 @@ tang issue view 1 log in rather than working around it. - Issue titles: prefix with the finding type — `Contradiction:`, `Question:`, `Violation:` — so the issue list reads as the project's open questions. + The rest of the title is the decision itself ("four origins or five?"), + not a topic label ("chargen thoughts"). + +### Issue body standard (binding) + +Every Tangled issue filed for Cameron is a **decision packet**, not a +status dump or agent diary. He must be able to open any issue and answer +it in under two minutes without reading the surrounding session. + +**Required sections, in this order:** + +1. **`## Question`** — one concrete question. Prefer a numbered multiple-choice + list (`1.` / `2.` / `3.` … plus `Something else (say what)`). Never leave + the ask buried in a paragraph of context. +2. **`## Why this is open`** — short analysis: what the docs/code currently + say, what conflict or gap forces a human call, and what is already decided + (so he does not re-litigate settled ground). Quote file paths; keep it to + a few sentences. +3. **`## Options`** — 2–4 real alternatives with one honest trade-off line + each (which pillar/clause it serves or strains). Tables are fine. +4. **`## Recommendation`** — one marked pick and a one-line reason. Turns the + issue into a yes/no override, not an essay question. +5. **`## What your answer unlocks`** — the mechanical next step (which + DESIGN.md / wiki page to amend, which ROADMAP item unblocks, when to + close the issue). + +**Hard rejects (do not file, or rewrite before leaving):** + +- A body that is only narrative / session notes with no singular question. +- A question that cannot be answered without opening other files first. +- Multiple unrelated decisions packed into one issue (split them). +- Jargon-dense prose that restates the wiki instead of asking for a call. + +If you find an existing open issue that fails this standard, rewrite it with +`tang issue edit` before doing other harvest work on it. An unanswerable +issue is process debt, same species as a stale `[OPEN]` marker. ## Tick etiquette -- 2.51.2