--- name: emergent-thinking description: Use the emergent-thinking CLI as a baseline-first local attention board. Write one bounded baseline first, then let external validation drive the next move. --- # Emergent Thinking Use `emergent-thinking` when a task is large enough that the model should stop free-writing and start externalizing state. The point is not to add ceremony. The point is to force explicit attention: - frame only enough to begin - write one bounded baseline - validate against reality early - create findings and proof debt from that reality - repair the earliest economical stage - let external evidence, not chat momentum, decide the next move Canonical rule source: - `references/board-protocol-rules.md` ## When To Use - The task is large enough that a zero-to-final plan is likely to drift. - A rough first pass can reveal hidden structure quickly. - Runtime, rendering, integration, or UX failures matter. - You need durable project-local reasoning state instead of chat-only memory. - You want explicit coordination instead of ad-hoc delegation. ## If Subagents Are Available If the current agent platform supports subagents, read this supplement before delegating: - `references/how-to-use-subagents.md` The base skill still works in single-agent mode. The supplement explains how to extend the same board workflow into coordinated multi-agent execution without adding special subagent-only CLI commands. The default assumption is still single-agent. Only enable subagents when: - the parallel slices are clear - the integration coupling is low - the acceptance can be localized ## Core Discipline - One board per project/session. - Prefer one accumulating mainline. - Default to `@tip` unless you intentionally want an older position. - Treat active `goal/...`, `constraint/...`, and `finding/...` atoms as mandatory pressure. - The baseline is allowed to be ugly, incomplete, and wrong. - The baseline exists to create a real position. - The final artifact is not the baseline with endless patches. - Treat `proof record` as a first-class move. - Do not claim convergence without proof debt actually closing. - Once the board reaches `ready` with `lineDebt=0` and no threats, stop framing and start a bounded baseline pass. - At `ready`, the remaining proof debt is implementation/validation work, not a reason to keep modeling in place. - After browser QA, tests, runtime failures, or user feedback, update the board before the next major implementation pass. - Treat external validation as the highest-quality reward signal. A passing test, screenshot, runtime check, or benchmark result should outweigh a purely verbal proof. - Do not end on a contested board just because you already have a revised artifact. - If validation finds a real defect, the loop is not “documented”; it is still open. - Do not compress many hard requirements into one umbrella `goal/main`. Split them into independently testable goals and constraints so the board can keep pressure on each one. - Search should stay sparse. Expand only the few next moves that most reduce threats, line debt, or proof debt, then re-evaluate before widening again. ## Baseline-First Loop 1. Create the board: - `emergent-thinking board create -s /` 2. Frame only enough to begin: - add at least one `problem` - add the hard `goal/...` surface - add hard `constraint/...` atoms when needed - add at least one candidate `path/...` - add the main `tool/...` surface 3. Select the mainline: - `emergent-thinking line select -s -a ` 4. Inspect the pressure on that line: - `emergent-thinking search show -s -d 4` - or `emergent-thinking board judge -s ` 5. Pay down structural debt until the board reaches `ready`. 6. Write one bounded baseline artifact: - `index.baseline.html` - `app.baseline.ts` - `worker.baseline.ts` 7. Inspect or run the baseline enough to expose real pressure. 8. Feed the result back: - failing reality should create or preserve `finding` pressure - passing reality should close proof debt 9. Decide what to keep and what to replace: - patch the baseline - rebuild slices - rebuild most of it 10. Continue the normal emergent loop from that real position: - select the line - inspect pressure - implement a bounded slice - validate externally - feed findings and proofs back into the board 11. Repeat until the board reaches `converged`. ## Hard Stop Rules - For non-trivial tasks, do not jump from light framing straight to the final artifact. - For non-trivial tasks, create a `*.baseline.*` artifact before deep decomposition. - The baseline does not count as the final artifact. - Do not let the baseline become untouchable just because it exists. - If repeated patching increases entropy, stop patching and reselect the path. - If evidence shows the baseline assumption was wrong, change the path instead of defending the baseline. - After any external failure, create or preserve a `finding/...` atom with a stable id. - Connect that `finding/...` back to the selected line or broken target with `cell upsert ... -e threatens ...`. - Do not write the final answer while any `finding/...` still threatens the selected line or its supported goal. - After fixing a defect that previously threatened the selected line, re-run the same validation. - If the validation now passes, immediately record a passing proof against the previously threatened target. - Before the first implementation pass, run `search show` and resolve the selected line's missing structure. - In practice that means the selected `path/...` should already support a goal and use at least one `tool/...` before coding starts. - Do not ignore `search show` responses that point at the selected line. Either satisfy them or deliberately replace the line. - For exact `line.structure-sweep` semantics, follow `references/board-protocol-rules.md` instead of improvising. - Before final output, re-run both: - `search show -s -d 4` - `board judge -s ` - If `search show` still reports threats on the mainline, or `board judge` is not `converged`, continue the repair loop instead of answering. - A board that still has an unproved active goal or active constraint is not converged, even if a draft artifact already exists. - Findings must be as narrow as the direct observation supports. Do not upgrade a partial rendering failure into a total-system failure unless the evidence really shows that. ## Canonical Moves - `board create/show/judge/list` - `atom upsert/list/show` - `cell upsert/list` - `line select/show` - `proof record/list` - `search next/show` - `compact` - `dict get/get-all/set/unset` ## Practical Heuristics - Use short stable ids when possible: `problem/core`, `goal/main`, `path/mainline`, `tool/sqlite`. - Prefer one hard requirement per atom when the task is complex enough to test in pieces. - Do not invent extra categories when an existing atom kind already fits. - A board that keeps adding atoms without selecting a line is usually stuck in framing. - If the baseline already has one good slice, preserve it and replace only the failing slices. - If the baseline reveals a deep architectural mistake, do not keep patching around it. - A selected line with no proof is not done; it is merely ready to be contested. - If several requirements would need separate browser checks, they should usually be separate goals or constraints. - If `search show` returns a batch of plain structural fixes such as `line.attach-goal` or `line.attach-tool`, apply that whole sweep before pausing to rethink. - When a whole sweep is obvious, prefer one JSON request sequence over many tiny CLI calls. - Do not stop after partially reducing `lineDebt`. Finish the current structural sweep, then re-run `search show`. - If a defect specifically breaks the chosen path, create a `finding` that threatens that path instead of burying it in prose. - If browser console shows `SyntaxError`, `ReferenceError`, or `TypeError`, treat that as a blocking finding, not as a minor note. - For canvas, Pixi, WebGL, or other custom-rendered surfaces, accessibility snapshots usually prove controls, not the rendered scene itself. - For those surfaces, pair the snapshot with screenshot evidence before deciding whether the scene rendered correctly. - Distinguish "surface rendered", "surface rendered but domain content missing", and "surface failed entirely". - If the board frame is visible but pieces are missing, prefer a narrow finding such as `finding/pieces-missing` instead of `finding/board-not-rendering`. - If a selected path has no explicit `tool/...`, expect the board to stay structurally incomplete even when other parts look good. - If the platform supports subagents, let the main agent keep the board coherent and delegate only bounded slices such as exploration, focused implementation, validation, or critique. - If the slices are not cleanly parallel, the integration surface is high-coupling, or the acceptance only makes sense at full-system scope, do not delegate. - A good default test is: - can one worker own one slice without changing global direction? - can the result be validated locally? - can the main agent integrate it without a long merge-and-rethink pass? - If any answer is "no", stay single-agent. - Use `compact` for handoff instead of dumping the entire board JSON into the next prompt. ## JSON-Friendly Interface For models, JSON array mode is usually the cheapest stable form: ```bash emergent-thinking '["atom","upsert","demo/x","@tip","path/mainline","path",":Describe the next line."]' emergent-thinking '["cell","upsert","demo/x","@tip",null,"path/mainline","supports","goal/main"]' emergent-thinking '["proof","record","demo/x","@tip","path/mainline","pass",":Validated by tests."]' emergent-thinking '[["atom","upsert","demo/x","@tip","goal/main","goal",":Reach the target."],["atom","upsert","demo/x","@tip","tool/sqlite","tool",":Use sqlite."],["cell","upsert","demo/x","@tip",null,"path/mainline","uses","tool/sqlite"]]' ``` Content specs: - `:literal text` - `file:./note.md` - `http://...` - `https://...` Sequence mode returns the final command result plus a `count`. Keep `atom.upsert` and `proof.record` bodies inline in sequence mode instead of relying on stdin. ## Anti-Patterns - Treating the board as a diary while solving the real problem elsewhere. - Adding many atoms but never selecting a line. - Treating `search` output as decorative instead of actionable. - Implementing after `framing` because “the task seems obvious”. - Treating the baseline as the real design. - Letting `*.baseline.*` silently become `*.final.*`. - Repeatedly patching a baseline whose structure is already disproved. - Running validation and not feeding the result back into the board. - Stuffing five different acceptance criteria into one `goal/main` and then proving only that umbrella summary. - Creating an oversized finding because the validator only looked at one weak signal. - Forcing one-shot completion when the board is clearly still contested. - Producing a revised artifact and then stopping without proving that the threatening finding is actually closed.