cyc-stack 0.0.0-stage → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/.agents/plugins/marketplace.json +12 -0
  2. package/.claude-plugin/marketplace.json +14 -0
  3. package/.claude-plugin/plugin.json +17 -0
  4. package/.codex-plugin/plugin.json +33 -0
  5. package/.cursor-plugin/marketplace.json +13 -0
  6. package/.cursor-plugin/plugin.json +19 -0
  7. package/INSTALL.md +153 -0
  8. package/LICENSE +21 -0
  9. package/README.md +436 -2
  10. package/bin/cyc.mjs +294 -0
  11. package/catalog/playbooks.json +20 -0
  12. package/docs/README.md +30 -0
  13. package/docs/assets/cyc-method-library.svg +39 -0
  14. package/docs/assets/cyc-overview.svg +44 -0
  15. package/docs/assets/cyc-readme-banner-mobile.svg +31 -0
  16. package/docs/assets/cyc-readme-banner.svg +39 -0
  17. package/docs/assets/cyc-workflow-diagram.svg +415 -0
  18. package/docs/code-quality.md +42 -0
  19. package/docs/context.md +40 -0
  20. package/docs/cyc-method-map.md +58 -0
  21. package/docs/cyc-workflow.md +188 -0
  22. package/docs/engineering/code-standards.md +103 -0
  23. package/docs/engineering/domain-design.md +81 -0
  24. package/docs/engineering/failure-handling.md +105 -0
  25. package/docs/impact-analysis.md +70 -0
  26. package/docs/installation.md +198 -0
  27. package/docs/onboarding-recovery.md +75 -0
  28. package/docs/principles.md +49 -0
  29. package/docs/project-tools.md +108 -0
  30. package/docs/response-standard.md +202 -0
  31. package/docs/runtime.md +249 -0
  32. package/docs/skill-contract.md +70 -0
  33. package/docs/skill-craft.md +23 -0
  34. package/docs/validation.md +39 -0
  35. package/docs/work-assessments.md +180 -0
  36. package/hooks/claude.json +10 -0
  37. package/hooks/codex.json +28 -0
  38. package/hooks/cursor.json +8 -0
  39. package/methods/cyc-build/SKILL.md +65 -0
  40. package/methods/cyc-build/references/file-writes.md +11 -0
  41. package/methods/cyc-challenge/SKILL.md +48 -0
  42. package/methods/cyc-context/SKILL.md +76 -0
  43. package/methods/cyc-context/references/evidence.md +27 -0
  44. package/methods/cyc-context/references/templates.md +54 -0
  45. package/methods/cyc-context/scripts/evidence.mjs +61 -0
  46. package/methods/cyc-correct/SKILL.md +43 -0
  47. package/methods/cyc-deliver/SKILL.md +52 -0
  48. package/methods/cyc-design/SKILL.md +50 -0
  49. package/methods/cyc-design/frontend-design/SKILL.md +43 -0
  50. package/methods/cyc-design/frontend-design/references/color.md +77 -0
  51. package/methods/cyc-design/frontend-design/references/craft-rules.md +61 -0
  52. package/methods/cyc-design/frontend-design/references/decision-sheet.md +110 -0
  53. package/methods/cyc-design/frontend-design/references/experience-review.md +58 -0
  54. package/methods/cyc-design/frontend-design/references/generic-tells.md +76 -0
  55. package/methods/cyc-design/frontend-design/references/layout-archetypes.md +188 -0
  56. package/methods/cyc-design/frontend-design/references/reference-standards.md +38 -0
  57. package/methods/cyc-design/frontend-design/references/typography.md +51 -0
  58. package/methods/cyc-design/frontend-design/references/ux-foundations.md +45 -0
  59. package/methods/cyc-design/frontend-design/references/visual-material.md +42 -0
  60. package/methods/cyc-error-ledger/SKILL.md +53 -0
  61. package/methods/cyc-error-ledger/references/entry-format.md +38 -0
  62. package/methods/cyc-explore/SKILL.md +41 -0
  63. package/methods/cyc-frame/SKILL.md +49 -0
  64. package/methods/cyc-impact/SKILL.md +64 -0
  65. package/methods/cyc-reflect/SKILL.md +48 -0
  66. package/methods/cyc-remember/SKILL.md +53 -0
  67. package/methods/cyc-scout/SKILL.md +67 -0
  68. package/methods/cyc-setup/SKILL.md +60 -0
  69. package/methods/cyc-teach/SKILL.md +40 -0
  70. package/methods/cyc-understand/SKILL.md +40 -0
  71. package/methods/cyc-understand/references/diagnose.md +53 -0
  72. package/methods/cyc-verify/SKILL.md +87 -0
  73. package/methods/cyc-verify/references/recipe.md +53 -0
  74. package/package.json +91 -4
  75. package/plugin.json +40 -0
  76. package/rules/cyc-delivery.mdc +33 -0
  77. package/scripts/baseline-worker.mjs +10 -0
  78. package/scripts/catalog.mjs +29 -0
  79. package/scripts/claude-project-hook.mjs +12 -0
  80. package/scripts/context-review.mjs +600 -0
  81. package/scripts/host-activation.mjs +66 -0
  82. package/scripts/install.mjs +387 -0
  83. package/scripts/onboarding.mjs +110 -0
  84. package/scripts/packet.mjs +107 -0
  85. package/scripts/project-tools.mjs +196 -0
  86. package/scripts/recovery.mjs +66 -0
  87. package/scripts/response-gate.mjs +105 -0
  88. package/scripts/response-hook.mjs +237 -0
  89. package/scripts/response-mode.mjs +12 -0
  90. package/scripts/run-gate.mjs +264 -0
  91. package/scripts/runtime.mjs +1832 -0
  92. package/scripts/source-hash-worker.mjs +5 -0
  93. package/scripts/source-snapshot.mjs +405 -0
  94. package/scripts/test-output.mjs +268 -0
  95. package/scripts/work-review.mjs +326 -0
  96. package/skills/cyc/SKILL.md +132 -0
  97. package/skills/cyc/references/playbooks/bug-fix.md +13 -0
  98. package/skills/cyc/references/playbooks/evaluate.md +13 -0
  99. package/skills/cyc/references/playbooks/experience.md +7 -0
  100. package/skills/cyc/references/playbooks/explore.md +9 -0
  101. package/skills/cyc/references/playbooks/feature.md +14 -0
  102. package/skills/cyc/references/playbooks/handoff.md +11 -0
  103. package/skills/cyc/references/playbooks/investigation.md +7 -0
  104. package/skills/cyc/references/playbooks/performance.md +7 -0
  105. package/skills/cyc/references/playbooks/plan.md +11 -0
  106. package/skills/cyc/references/playbooks/refactor.md +12 -0
  107. package/skills/cyc/references/playbooks/reflect.md +11 -0
  108. package/skills/cyc/references/playbooks/resume.md +11 -0
  109. package/skills/cyc/references/playbooks/review.md +9 -0
  110. package/skills/cyc/references/playbooks/teach.md +11 -0
  111. package/skills/cyc/references/playbooks/verify.md +7 -0
@@ -0,0 +1,49 @@
1
+ ---
2
+ name: cyc-frame
3
+ description: "Turn a request into a destination, scope, and acceptance criteria someone could check, interviewing the user only on real decisions. Use at the start of a task, when the request is vague, or when feedback shows the goal was misunderstood."
4
+ ---
5
+
6
+ # Frame the work
7
+
8
+ Name the destination before choosing the road. A good frame lets another skill say what "done" means without guessing. Use the [handoff contract](../../docs/skill-contract.md) inside a CYC chain.
9
+
10
+ ## The core loop
11
+
12
+ 1. **Name the destination in one sentence, in the user's words.** "A student can mark homework finished and it stays finished after refresh." Keep their chosen mechanism unless it cannot reach the destination; if so, say why.
13
+ 2. **Set the quality bar at excellent.** Write what excellent looks like in *this* codebase for this task: its conventions, test style, error handling, and performance expectations. Name the shortcuts that would fall short of it (the tells a senior reviewer would reject), and what must survive every revision. Some of this only becomes clear after the user sees a draft; when it does, raise the bar here.
14
+ 3. **Name the stage.** Exploring an idea, choosing an approach, building, or evaluating. "What do you think about X?" is exploring. Do not build it.
15
+ 4. **Look up facts yourself; ask the user only for decisions.** Existing storage, frameworks, and conventions are facts: read the code or send a subagent. Whether finished items hide or move is a decision: ask.
16
+ 5. **Ask the frontier, not a questionnaire.** The frontier is every open decision whose prerequisites are settled. Ask all of them in one numbered round, each with your recommended answer and a one-line reason, so the user can reply "yes to all" or change one. Stop when the frontier is empty or the remaining choices are cheap to reverse.
17
+ 6. **Write acceptance criteria as checks.** Each criterion is observable: "After reload, the assignment still shows as finished." Include preserved behavior ("Adding homework still works"). No invented numbers for taste; mark those "user judgment".
18
+ 7. **Write the out-of-scope list.** Name the tempting extras you are not doing (accounts, sync, reminders). This protects scope better than a vague "keep it small".
19
+
20
+ ## Done when
21
+
22
+ - The destination sentence and the quality bar exist.
23
+ - Every criterion could be marked pass or fail by someone reading the result.
24
+ - There is at least one preserved-behavior criterion and an out-of-scope list.
25
+ - No open question remains that would change the solution; cheap choices were made and stated as assumptions.
26
+
27
+ ## Question format
28
+
29
+ ```text
30
+ 1. Should finished homework disappear or move to a "Finished" section?
31
+ Recommended: move to a collapsed section. Hiding makes accidental clicks unrecoverable.
32
+ 2. Persist per browser (current localStorage) or per account?
33
+ Recommended: per browser. The app has no accounts yet.
34
+ ```
35
+
36
+ ## Anti-patterns
37
+
38
+ | Name | The tell | Fix |
39
+ | --- | --- | --- |
40
+ | Interrogation | Asking the user where the save code lives | Read the code |
41
+ | Drip questions | One question per turn over five turns | Ask the whole frontier at once |
42
+ | Menu without a pick | "Option A or B?" with no recommendation | Recommend one, give the reason |
43
+ | Mechanism swap | User asked for a button, frame says "keyboard shortcut" | Keep their mechanism or explain the conflict |
44
+ | Bare minimum bar | Criteria only say "it works" | Add what excellent looks like in this codebase |
45
+ | Vibe criteria | "Works well", "clean UI" | Rewrite as an observation, or mark user judgment |
46
+
47
+ ## Handoff
48
+
49
+ Pass the destination, quality bar, stage, criteria (with stable IDs), preserved behaviors, out-of-scope list, assumptions, and user decisions to [Understand](../cyc-understand/SKILL.md). If feedback later shows the frame was wrong, update it here, keep the failed criterion on record, and name which downstream work is now invalid.
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: cyc-impact
3
+ description: "Find what a change could break beyond the lines it edits, and prove the fact that makes it safe. Use before any substantive change, when a change touches shared state, storage, or interfaces, or when a build or verify step reveals an unexpected dependency."
4
+ ---
5
+
6
+ # Map the blast radius
7
+
8
+ Listing callers is not the job; search does that in a second. The job is to find the **load-bearing fact**, the one thing the change is safe *because of*, and prove it. Read-only: finding an affected area does not authorize editing it. See the [impact-analysis standard](../../docs/impact-analysis.md) and [handoff contract](../../docs/skill-contract.md).
9
+
10
+ ## The core loop
11
+
12
+ 1. **Check the history.** Read the [context](../cyc-context/SKILL.md) docs and [error ledger](../cyc-error-ledger/SKILL.md) entries for the touched paths. Recorded gotchas are the first connections to check.
13
+ 2. **Start from the chain.** Take the call chain from [Understand](../cyc-understand/SKILL.md). Mark every hop the change will touch.
14
+ 3. **Trace outward from the changed data, not the changed file.** Who else reads this field, row, key, or event? Who writes it? Search for the data name, the storage key, and the event name, not just the import.
15
+ 4. **Look where search stops.** Imports miss the dangerous connections. Check each of these that exists in the project:
16
+ - saved data already on disk or in a database (old records missing the new field)
17
+ - wire formats: API responses, JSON contracts, generated clients
18
+ - config, feature flags, route or plugin registration by string name
19
+ - scheduled jobs, webhooks, queues, and event subscribers
20
+ - other languages or services reading the same store
21
+ - derived UI: counts, filters, sort orders, badges, empty states
22
+ - timing: concurrent writes, teardown, running the action twice
23
+ 5. **Name the load-bearing fact.** "This is safe because every reader goes through `getAssignments()`, which defaults missing fields." Then prove it at the highest rung you can reach:
24
+
25
+ | Rung | Evidence |
26
+ | --- | --- |
27
+ | 1 | Someone said so |
28
+ | 2 | Pointed at the line |
29
+ | 3 | Walked through the failure case by reading |
30
+ | 4 | Ran a script or test that shows it |
31
+ | 5 | Reproduced it in the running app |
32
+
33
+ Aim for rung 4 on anything touching storage or shared interfaces. Report the rung reached for each fact.
34
+ 6. **Split the map into Risks and Cleared.** Risks: connections that could break, each with the check that would catch it. Cleared: connections you checked and why they are safe, with the rung. A map with no Cleared section usually means nothing was actually checked.
35
+ 7. **Name the cheapest check before build.** The one test or script that would most likely catch a mistake. It goes straight into [Verify](../cyc-verify/SKILL.md)'s matrix.
36
+
37
+ Keep it proportionate. A copy change inside one component needs a two-line map. A storage or interface change needs the full loop.
38
+
39
+ ## Done when
40
+
41
+ - The load-bearing fact is stated and proven at rung 4 or higher, or its lower rung is stated with why.
42
+ - Every Risk row has a check that would show it red.
43
+ - The search list in step 4 was applied, and skipped categories have a reason ("no background jobs in this project: searched for cron, schedule, queue").
44
+
45
+ ## Output
46
+
47
+ | Location | Connection and evidence | Risk or Cleared | Rung | Check |
48
+ | --- | --- | --- | --- | --- |
49
+ | `storage.ts:15` loadAll | Reads saved assignments; old records lack `finished` | Risk | 4 (script loaded fixture) | Legacy-record load test |
50
+ | `Counter.tsx:8` | Counts `filter(a => !a.finished)` | Risk | 2 | Count after mark-finished |
51
+ | `ReminderJob` | Registered by name in `jobs.json`; reads same store | Cleared: skips unknown fields | 3 | none needed |
52
+
53
+ ## Anti-patterns
54
+
55
+ | Name | The tell | Fix |
56
+ | --- | --- | --- |
57
+ | Caller dump | A list of every file that imports the module | Find the load-bearing fact instead |
58
+ | Import-only search | Only `import` statements were searched | Search the data name, key, and event |
59
+ | Unproven "safe" | "Should be fine" with no rung | Prove it or label it rung 1 |
60
+ | Scope creep | Map item becomes "also fix the reminder job" | Map it; changing it needs the user's scope |
61
+
62
+ ## Handoff
63
+
64
+ Pass the Risks table, the load-bearing fact, and the cheapest check to [Design](../cyc-design/SKILL.md) and on to Verify. When build or verify finds something the map missed, come back here, add it, and name which checks it adds. That missed connection is also worth a note for [Reflect](../cyc-reflect/SKILL.md).
@@ -0,0 +1,48 @@
1
+ ---
2
+ name: cyc-reflect
3
+ description: "Turn what went wrong or right in finished work into specific proposed edits to CYC skills, checks, or project rules, each tied to evidence. Use when the user says \"reflect\", \"what did we learn\", or \"improve the workflow\", after a task needed corrections, or when a missed dependency or repeated mistake appeared."
4
+ ---
5
+
6
+ # Learn from outcomes
7
+
8
+ The output is proposed edits, not a list of lessons. A lesson that doesn't change a file changes nothing. Follow the [handoff contract](../../docs/skill-contract.md) and the [skill craft guide](../../docs/skill-craft.md).
9
+
10
+ ## The core loop
11
+
12
+ 1. **Collect the moments that mattered.** User corrections, failed checks, missed dependencies, rework, and things that went unusually well. Read the relevant run's `review.md`, handoffs and verification receipts, the selected error ledger, and available transcript or decision log. Use an improvements log only if the project already maintains one; the controller does not generate `.cyc/runs/improvements.tsv`. An AI-written summary is secondary evidence.
13
+ 2. **Read each moment through three lenses.**
14
+ - **Judgment:** what decision was wrong or right, and what would have led to the right one?
15
+ - **Tooling:** what check, script, or search would have caught it mechanically?
16
+ - **Beneath the obvious:** what is the learning under the first explanation? ("Missed the reminder job" may really be "we only searched imports.")
17
+ 3. **Pick the strongest mechanism that would prevent it.** In order:
18
+ 1. make it impossible (a type or schema)
19
+ 2. a test, lint, or CI check
20
+ 3. a script or helper the skill tells the agent to run
21
+ 4. a sharper step or anti-pattern in an existing skill
22
+ 5. a new sentence of prose, as the last resort
23
+ 4. **Apply the no-op test to every proposed skill edit.** Would a strong model behave differently with this sentence? If not, drop it.
24
+ 5. **Prefer editing an existing skill over creating one.** A new skill needs recurring evidence across tasks.
25
+ 6. **Write each proposal as an edit.** Target file, the exact change, the evidence (quoted correction or failed check), where it should *not* apply, and how you would tell if it made things worse.
26
+
27
+ ## Acceptance for a proposal
28
+
29
+ Keep a proposal only if it is: tied to a real moment, specific enough to apply, decision-changing, not already covered, and durable (it will still be true next month). Drop one-off facts like commit hashes and versions; keep the pattern behind them.
30
+
31
+ A finding that the skill didn't trigger when it should have is a proposal to tune the skill's **description**, not its body.
32
+
33
+ ## Done when
34
+
35
+ Each surviving proposal names a file, the change, its evidence, and its counter-case. "No supported lesson this time" is a valid result.
36
+
37
+ ## Anti-patterns
38
+
39
+ | Name | The tell | Fix |
40
+ | --- | --- | --- |
41
+ | Lesson list | "We learned to be more careful" | Write the file edit or drop it |
42
+ | Prose for a machine job | Adding "remember to check X" when a script could | Build the check |
43
+ | One-off promotion | A single correction becomes a global rule | Wait for recurrence or ask the user |
44
+ | Authorship drift | The agent's idea recorded as the user's insight | Keep who said what |
45
+
46
+ ## Handoff
47
+
48
+ Return proposals to the user. Apply them only when the current request authorizes editing skills or rules.
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: cyc-remember
3
+ description: "Keep a running decision log during work and rebuild context when resuming, so the next session knows what was decided, why, and what's next. Use at checkpoints, before stopping mid-task, when the user says \"catch me up\" or \"where did I leave off\", or when handing work to another session or tool."
4
+ ---
5
+
6
+ # Remember what matters
7
+
8
+ Write memory as you go, not in a batch at the end. Follow the [handoff contract](../../docs/skill-contract.md).
9
+
10
+ ## During work: the decision log
11
+
12
+ Append one row per consequential decision to `.cyc/runs/<runId>/decisions.tsv`, or `.cyc/runs/decisions.tsv` outside a run:
13
+
14
+ ```text
15
+ time stage decision why evidence who
16
+ 2026-09-25T14:02 design finished is a boolean, default false no other states requested storage.ts:15 user
17
+ 2026-09-25T14:20 build count derives from same filter avoids drift Counter.tsx:8 agent
18
+ ```
19
+
20
+ - **evidence** is a pointer (file:line, command, or URL), never a paragraph.
21
+ - **who** is `user` (they decided), `agent` (you proposed; not yet adopted), or `adopted` (you proposed, the user agreed).
22
+ - Never edit a row. If a decision changes, append a new row that supersedes it.
23
+
24
+ ## At a checkpoint
25
+
26
+ Write a capsule of five bullets or fewer: destination, current stage, what's proven (with evidence pointers), what's open, and the next single action. Tag each open thread with one status: `[done]`, `[in progress]`, `[blocked: reason]`, or `[dropped: reason]`. Untagged threads count as not done.
27
+
28
+ Point to canonical component context and its relevant constraints/checks instead of copying them into the capsule. Retain verified reusable findings through [Context](../cyc-context/SKILL.md) before final verification; a local decision log alone is not shared project memory. Keep adoption status and technical evidence distinct.
29
+
30
+ ## When resuming
31
+
32
+ Read `node <cli> run recover --run ID` for the existing run before changing its state. It preserves the recorded budget and exposes historical check receipts without making them current proof. Use the run ID from this task's records, not another session's latest run. If the ID is missing or several match, reconstruct the association from the task records before choosing. A paused run can resume; a blocked run first needs its recorded prerequisite resolved. An exhausted, halted or stopped run needs an explicit continuation decision rather than an automatic fresh budget.
33
+
34
+ 1. Read the capsule and decision log first. They are the record; don't re-derive everything from scratch.
35
+ 2. Check for drift: compare them with current files and git state. Recheck only what drift affects.
36
+ 3. Treat an earlier "tests passed" as history, not a current result. Rerun before relying on it.
37
+ 4. Preserve the user's changes made since the checkpoint.
38
+ 5. Report what changed since the checkpoint and the next action. State what remains in place without calling it a backup or claiming earlier commands had no side effects. Keep agent-caused and user-caused changes distinct only when evidence establishes authorship. If help is needed, reuse the existing review, failing receipt and recorded prerequisite as the handoff; do not send it to a teammate without authorization.
39
+
40
+ ## Done when
41
+
42
+ Another worker could read the capsule and log and state what's decided, by whom, what's proven, and the safe next step, without guessing.
43
+
44
+ ## Anti-patterns
45
+
46
+ | Name | The tell | Fix |
47
+ | --- | --- | --- |
48
+ | End-of-day dump | The log is written from memory at the end | Append when the decision happens |
49
+ | Authorship blur | An agent idea recorded as the user's choice | Use the `who` column honestly |
50
+ | Stale proof | Reusing old test results after resuming | Rerun |
51
+ | Silent scope shrink | "Catch me up on everything" answered from the last hour only | Say what range you covered |
52
+
53
+ Keep credentials and unrelated personal data out of every record. Use the controller's pause and resume commands; never edit its state files.
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: cyc-scout
3
+ description: "Get from request to a concrete plan in one or two minutes: one parallel batch of searches and reads, then a short plan naming the files to change, the consumers to keep consistent, and the checks to run. Use at the start of any feature, bug fix, refactor, or verification task before editing code."
4
+ ---
5
+
6
+ # Scout, then build
7
+
8
+ For a new website, composed interface or visual redesign, use the [frontend design method](../cyc-design/frontend-design/SKILL.md) before choosing structure or acceptance criteria: write `design/decisions.md` (archetype, typeface pair, palette values, signature element, rejection condition) and, for several sites, the set-divergence table. A palette, image presence and readability cannot be the entire visual criterion. Keep this within the user's criterion count; a narrow repair preserves the existing direction.
9
+
10
+ Scouting establishes the affected behavior and the next justified action. For an implementation route, aim for a short plan and a useful first edit; for Investigation, Review, or Verify, establish the explanation or checks without assuming permission to change the product. Expand investigation for consequential uncertainty; verification cannot justify skipping relevant project history or a misunderstood goal.
11
+
12
+ For user updates, follow the shared [progress standard](../../docs/response-standard.md#progress-updates): explain the observed behavior and the likely or confirmed mechanism in short, readable prose, then the next useful change or unresolved question. File counts alone do not explain a discovery.
13
+
14
+ Build the engineer's picture of the affected system: connect the relevant input, state, and readers; explain how checked project history informs the approach and which trade-off matters. Follow the [engineering understanding standard](../../docs/response-standard.md#engineering-understanding-throughout-the-work). Agreement on scope is not evidence of comprehension; ask only for a consequential missing decision.
15
+
16
+ ## The pass
17
+
18
+ After locating the affected paths, run `node <cli> investigate --path <paths>` (or `--run <ID>` with a known scope). Read the returned records and recipe definitions. Run applicable investigation recipes when their prerequisites hold and effects are already authorized; explain unavailable checks. Reuse equivalent current evidence already returned by discovery rather than rerunning solely to create a receipt. Do this without a separate user request, and reuse the result until paths or evidence change. Missing recipes mean ordinary focused discovery, not a new documentation requirement. See [project tools](../../docs/project-tools.md).
19
+
20
+ 1. **One parallel batch, not a file-by-file tour.** In a single round of tool calls, run together:
21
+ - a search for the entry point (the visible string, route, function, or error message)
22
+ - a search for every reader and writer of the data you'll change (field name, storage key, event name, exported function)
23
+ - the existing feature map (if any), `docs/context/INDEX.md`, and the selected error ledger for these paths
24
+ - `git status` / `git diff --stat` when work is already in progress
25
+ 2. **Reuse what is established.** Read matching current component context, then inspect the affected functions and integration boundaries. Follow [Context](../cyc-context/SKILL.md) for revision/file-evidence checks; revalidate affected claims when dependencies drift. Reuse still-applicable impact knowledge, failed approaches, and check recipes rather than reconstructing them. Expand for missing consumers or consequential unknowns. State when no history applies. Choose **reuse, extend, repair, or create**, with evidence; use the project's existing capability map. Stop when affected behavior, intended files, consumers, and checks are understood.
26
+ When the change introduces or reshapes state, ownership, or an interface, use the [architecture questions](../../docs/code-quality.md#choose-a-structure-that-protects-the-contract) while choosing the approach. Name the authoritative state, permitted writers, and invariant at the real caller. Compare another shape only if consequential uncertainty remains; a familiar local change does not need a design exercise.
27
+
28
+ 3. **Write the plan in about ten lines:**
29
+
30
+ ```text
31
+ Goal: one sentence. Done when: original user criteria, grouped for the short plan with a retained criterion-to-check mapping.
32
+ Approach: reuse/extend/repair/create → existing capability and reason.
33
+ Context: relevant history, freshness, known failed approaches (or no match).
34
+ Change: file → what changes (one line each)
35
+ Keep consistent: consumer → why it depends on this (from the search)
36
+ Test: the checks that would show it broken
37
+ Open: only decisions that change the solution (with your recommendation)
38
+ ```
39
+
40
+ 4. **Explain consequential changes.** Current behavior → proposed change → reason → decision needed. Ask only when an unresolved answer changes the solution; bundle questions with a recommendation. Otherwise state supported assumptions and continue. Record alignment as clear or actually confirmed; unresolved consequential alignment is blocked, not assumed approved.
41
+ 5. **Record and move on.** If `run start` was given `scout`, Scout is already recorded: do not record it again, because a second record lands at Build. Otherwise `cyc run record --run ID --summary "<plan>" --assessment <scout.json>` for new implementation runs. The [assessment](../../docs/work-assessments.md) records context lookup/freshness, approach, alignment, and stable consumer IDs/checks, including directly affected behavior. Keep JSON in the run directory. Advisory routes retain ordinary handoffs.
42
+
43
+ ## Scale by risk, not by habit
44
+
45
+ - **Normal work:** the pass above. Do not add paperwork or invent alternatives without a real decision to resolve. For visual frontend work, a useful first implementation can resolve the actual composition with meaningful content and assets; source-edit speed is not a reason to settle for a generic scaffold.
46
+ - **High risk** (auth, payments, data migrations, deletes, public interfaces): also run [Challenge](../cyc-challenge/SKILL.md) on the plan before building. It's one focused pass, not a new research phase.
47
+ - **Bugs:** include getting the failure to reproduce in the same batch (run the failing test or request). See the [diagnose branch](../cyc-understand/references/diagnose.md) only if it doesn't reproduce quickly.
48
+
49
+ The detailed skills ([Understand](../cyc-understand/SKILL.md), [Impact](../cyc-impact/SKILL.md), [Design](../cyc-design/SKILL.md)) are reference material for when something is genuinely unclear. Don't read them by default.
50
+
51
+ ## Done when
52
+
53
+ The findings name the affected files, consumers supported by inspection, checks to run, and the next stage for the selected route. For implementation, begin a safe, useful test or reversible slice once the plan is ready. For advisory work, pass the supported findings onward without editing the product. If investigation takes longer than expected, identify the unresolved question; surface a real blocker promptly. Never defer a critical permission, data-loss, or interface-contract question on the assumption that verification will catch it.
54
+
55
+ ## Anti-patterns
56
+
57
+ | Name | The tell | Fix |
58
+ | --- | --- | --- |
59
+ | Serial tour | One file read per step, narrating each | Batch searches and reads in parallel |
60
+ | Reading for completeness | Understanding code paths the change doesn't touch | Stop when every changed file and consumer is named |
61
+ | Paperwork | Tables, evidence rungs, category checklists | Ten-line plan |
62
+ | Pre-verifying | Measuring or testing hypotheticals before any edit | Build, then let the verify loop measure |
63
+ | Re-reading instructions | Opening unrelated methods at every step | Load needed instructions once; preserve required outcomes |
64
+
65
+ ## Handoff
66
+
67
+ Pass the findings to the stage returned by `run next`: Build for implementation, Challenge for review, Verify for verification, Explore for experience work, or Deliver for investigation. Advisory Scout establishes an evidence-backed explanation or review scope, not permission to edit. If later work finds a consumer the plan missed, update the plan and relevant retained context before verification.
@@ -0,0 +1,60 @@
1
+ ---
2
+ name: cyc-setup
3
+ description: "Set up CYC in the current project: activate it, find the project's real test, lint, and type-check commands, write them into the CYC config, and confirm everything works. Use when the user says \"set up cyc\", \"activate cyc\", \"install cyc here\", or right after installing the CYC plugin."
4
+ ---
5
+
6
+ # Set up CYC in this project
7
+
8
+ Guide the developer from installation to one useful task. Keep installed files, configured checks, executed checks, and live host activation distinct. Use the existing project conventions and ask only about consequential missing decisions.
9
+
10
+ The CYC CLI is [bin/cyc.mjs](../../bin/cyc.mjs), two folders up from this skill. Resolve it to an absolute path and run it with `node`.
11
+
12
+ ## The core loop
13
+
14
+ 1. **Inspect readiness.** Run `node <cli> onboard`. If this request supplied CYC gate context, add `--host codex|claude --session <gate ID> --token <injected review token>`. Otherwise omit the token: native Codex/Claude session identity is detected when available, and missing prompt state is an actionable setup failure. Inspection runs no project commands and changes no files. Explain its first unresolved step in plain language, not the entire JSON report.
15
+ - A project manifest exists: the report includes `doctor` findings. Resolve actual installation conflicts while preserving customized files.
16
+ - Only a config exists: the project is configured, but confirm that the host supplies the plugin. Do not reinstall or overwrite a team's existing checks just to repeat onboarding.
17
+ - No config exists: continue with activation or the project installer, according to how the user obtained CYC.
18
+ 2. **Activate.** Run `node <cli> activate --dry-run`, show the planned files, then run it without `--dry-run`. This creates `.cyc/config.json` and `.cyc/.gitignore` only. It changes nothing else.
19
+ 3. **Find the real checks.** Use `onboard.evidenceSources` as pointers, then read the project's own sources of truth: CI workflow files (`.github/workflows`, `.gitlab-ci.yml`), `package.json` scripts, `Makefile`, `pyproject.toml`, `go.mod`, `Cargo.toml`, and contributing instructions. Discovery does not parse or endorse commands. CI is the best evidence of what the team actually trusts. Explain each recommended check through the behavior or error it can detect. If no checks exist, say so and propose one bounded behavior check grounded in the project; creating it requires appropriate task scope, and an always-successful command is not a substitute.
20
+ Read existing project recipes with `node <cli> recipe list`. Reuse actual investigation scripts and behavior checks. Register successful, reusable commands in the project's `docs/context/recipes.json` using the [project-tools contract](../../docs/project-tools.md), with concrete coverage, references, prerequisites, effects and expected outcomes. This is authorized project configuration work, not permission to publish or copy CYC's development recipes into the application. Keep mandatory checks in `verification.commands`; optional relevant tools do not replace them.
21
+ 4. **Propose the commands in one round**, each with the reason and your recommendation:
22
+
23
+ ```text
24
+ Proposed verification commands for .cyc/config.json:
25
+ 1. test npm test (runs in CI: .github/workflows/ci.yml:31) Recommended: yes
26
+ 2. typecheck npx tsc --noEmit (in CI) Recommended: yes
27
+ 3. lint npm run lint (in CI, ~40s) Recommended: yes
28
+ 4. e2e npm run test:e2e (needs a running server) Recommended: no, keep it in the verify recipe
29
+ ```
30
+
31
+ Never add a command you haven't seen defined in the project. Never guess. Prefer checks that finish in a few minutes: CYC runs them to verify every change (optional diagnostic baseline checks are off by default). Leave hour-long suites to CI or the verify recipe, and split one giant command into separate ones (unit, integration) so each can be run and judged on its own.
32
+ When no one can answer (an unattended run, or `/cyc` was invoked with instructions not to wait), do not stop: write only commands the project itself defines and runs (CI or a package script), prove them in step 7, and name them in the final handoff as configured checks. That disclosure is information, not a blocker.
33
+
34
+ Do all of this before `run start`. The controller captures the checks when a run starts and protects `.cyc/config.json` while it runs; an edit then halts the run, and `run start` refuses code playbooks while no checks exist.
35
+ 5. **Write the approved commands** into `verification.commands` as `{ "id", "command", "args": [], "timeoutMs" }`. Reuse already authorized team configuration; do not ask for approval again when the session already provides it. Do not change configuration beneath an active run. Split the executable from its arguments (`"command": "npm", "args": ["test"]`). On Windows, Node cannot launch `npm`, `npx`, or other `.cmd` shims directly, so wrap them: `"command": "cmd", "args": ["/c", "npm", "test"]`.
36
+ 6. **Respect existing conventions.** Reuse the project ledger through `context.ledgerPath`. If another hook already enforces response formatting, configure `delivery.presentation: "project"`; preserve that hook. CYC still enforces controller completion. Show these choices with the proposed commands.
37
+ 7. **Prove the configured commands run.** After inspecting their side effects and establishing authorization, run `node <cli> onboard --verify`. It runs the configured checks and saves `.cyc/runtime/onboarding-checks.json`, bound to the configuration and covered source. Read failures from that receipt. A passing exit that changes source is not passing setup verification; later edits make the result stale. This receipt is diagnostic and never replaces a task's `run verify`. Keep baseline checks off for ordinary runs. Report existing failures without fixing unrelated code unasked or weakening checks.
38
+ 8. **Check the hooks in the actual host.** `onboard` exits nonzero while setup is not ready. Follow the `host` step rather than treating passing project tests as activation. Missing state means inspect the exact hook definitions and host trust/settings, then open a fresh session or reload. Use the supported hook review UI; do not edit trust records or fabricate hook state. A missing injected token cannot be repaired by reading an older state file or inventing a Cursor tag in Codex/Claude.
39
+ With the current injected token, `pending` plus `canStartTask: true` means the prompt hook ran and the authorized first task can proceed. Do not wait for your own Stop before starting it. After the turn ends, a separate observation can confirm `passed` from matching prompt/Stop identity, exact review/response and unchanged hook/configuration bytes. A rejected draft remains pending repair; blocked/not-ready completion is not successful setup. Old, copied, legacy or changed evidence stays stale/unverified. Cursor retains its own conversation/tag correlation and cannot be certified by a constant token through this check.
40
+ Do not manually invoke a hook script and call it live activation. A missing table alone is not a reliable probe: project-owned presentation and alternative valid visuals change the requirements. Report the observed host/version and remaining limits; local editable trace evidence is not independent certification.
41
+ 9. **Connect setup to a first success.** If the user already requested a bounded task, continue that task through the existing orchestrator once prerequisites permit. Otherwise recommend a small task from inspected project evidence and let the user choose it before editing product behavior. Explain the outcome and the checks that would establish it. On delivery, connect one consequential change to its test and point to the existing review. Do not require practice or claim that an explanation proves understanding.
42
+
43
+ ## Done when
44
+
45
+ - The report separates installation, configuration, executed checks, and host activation, with actual evidence and one next action for any unresolved step.
46
+ - Configured commands have recorded results; failed, stale or unavailable results remain disclosed. A failed setup is not called ready.
47
+ - The first task is continued when already authorized, or a concrete recommendation is offered without inventing approval. Setup completion and task completion remain separate.
48
+
49
+ ## Anti-patterns
50
+
51
+ | Name | The tell | Fix |
52
+ | --- | --- | --- |
53
+ | Invented checks | Adding `npm test` to a project with no test script | Only use commands defined in the project |
54
+ | Silent writes | Changing config before showing the plan | Dry run first, then write |
55
+ | Fixing the baseline | "Tests were failing, so I fixed them" during setup | Report the failing baseline; fixing is a separate task |
56
+ | Committed secrets | Tokens or env values in config commands | Reference env vars by name only |
57
+
58
+ ## Handoff
59
+
60
+ Report what is ready, the first unresolved step, and its smallest next action. Cite setup and host evidence separately. `ok`/`ready` require passing setup phases; neither establishes first-task completion or human understanding. Suggest sharing the existing project configuration through the team's normal review process.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: cyc-teach
3
+ description: "Teach a concept through the learner's own project with a plain definition, a worked example from their code, and a small practice task. Use when the user says \"explain\", \"teach me\", \"help me understand\", \"why does this work\", or is a student or newer developer learning while building."
4
+ ---
5
+
6
+ # Teach through the real work
7
+
8
+ Aim for understanding the learner can use elsewhere, not a longer answer. Follow the [handoff contract](../../docs/skill-contract.md).
9
+
10
+ This method is for a requested lesson or practice. Ordinary implementation already includes explanations through the shared [engineering understanding standard](../../docs/response-standard.md#engineering-understanding-throughout-the-work); do not require a separate teaching playbook, quiz, or learner response to provide them.
11
+
12
+ ## The core loop
13
+
14
+ 1. **Find the starting point from what they said.** Their wording, their code, and past questions show their level. Don't give a placement quiz. If it's genuinely unclear, ask one question.
15
+ 2. **Define it plainly first.** One or two sentences with no jargon they haven't seen. "State is the data your app remembers between clicks."
16
+ 3. **Tie it to their code immediately.** Show where the concept lives in *their* project, with the file and line. Read the code first; never teach from an imagined version of it.
17
+ 4. **Build the picture in steps.** For a flow, draw A → B, then add C, then the return path. Do not start with the full diagram.
18
+ 5. **Show one decision and its tradeoff.** "We saved to localStorage because the app has no accounts. The cost: it doesn't sync across devices." This is where understanding forms.
19
+ 6. **Give the smallest complete answer, then stop.** Offer to go deeper; don't pre-empt it.
20
+ 7. **Offer one practice task on a nearby variation.** "Now make the *delete* button update the count the same way." Give hints in steps if they ask. Provide the solution when asked.
21
+ 8. **Check transfer, not recall.** Ask them to predict what happens in a new case ("What if two tabs are open?") rather than repeat the definition.
22
+
23
+ ## Done when
24
+
25
+ The explanation is correct, grounded in files you read, and pitched at their level, and practice is offered. Learning is only shown by the learner's own attempt or prediction. Delivering a lesson doesn't prove it landed; say so if no attempt was made.
26
+
27
+ ## Anti-patterns
28
+
29
+ | Name | The tell | Fix |
30
+ | --- | --- | --- |
31
+ | Jargon cascade | Explaining a term with three new terms | Define with words they already use |
32
+ | Generic example | A textbook "foo/bar" example | Use their project |
33
+ | Lecture | Five paragraphs before any code | Definition, then their code, then stop |
34
+ | Drama framing | "Here's the key insight", "this is the tricky part" | Just say it |
35
+ | Solving their practice | Writing the solution before they try | Hint in steps unless they ask |
36
+ | Invented voice | Presenting AI-written advice as the project creator's teaching | Label who wrote it; only use reviewed material as theirs |
37
+
38
+ ## Handoff
39
+
40
+ Return the explanation, the practice task, and what was actually assessed (for example, "the learner predicted the two-tab case correctly" or "no attempt yet"). If the learner needs to respond before continuing, return blocked on their participation.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: cyc-understand
3
+ description: "Build an evidence-backed model of how the existing system behaves, or reproduce and locate a failure. Use for \"how does X work\", \"why does X happen\", bug reports, anything broken, throwing, or slow, and before designing a change to unfamiliar code."
4
+ ---
5
+
6
+ # Understand the existing system
7
+
8
+ Produce a model of the real behavior that the next skill can rely on. Read-only unless an experiment is authorized. Follow the [handoff contract](../../docs/skill-contract.md) for labeling observed versus inferred claims.
9
+
10
+ **Something is broken?** Search the [error ledger](../cyc-error-ledger/SKILL.md) first, then use the [diagnose branch](references/diagnose.md). Its rule is "no red loop, no fix."
11
+
12
+ ## The core loop
13
+
14
+ 1. **Find relevant project evidence.** Once paths are known, use `node <cli> investigate --path <paths>` to retrieve matching [context](../cyc-context/SKILL.md) and recipes; reuse an existing Scout result while it applies. Run relevant investigation recipes when their prerequisites hold and effects are authorized; otherwise explain the specific unavailable check. Consult project instructions, terminology and test layout as needed. Use the project's vocabulary, explaining a user/code naming difference once. The [project tools guide](../../docs/project-tools.md) covers discovery and execution.
15
+ 2. **Find the real entry point.** The route, handler, command, event, or component where the behavior starts. Search for the user-visible string or the route first; it is usually faster than guessing file names.
16
+ 3. **Trace the path end to end.** Entry, validation, state change, persistence, and what reads the result. Write it as a chain with file:line for each hop:
17
+ `click → Card.onFinish (Card.tsx:42) → store.update (store.ts:88) → saveAll (storage.ts:15)`
18
+ 4. **Check the user's claims against the code.** If the user said "it saves to the server" and it writes localStorage, surface that contradiction immediately. It usually changes the plan.
19
+ 5. **Observe when reading is ambiguous.** Run the code, print the stored value, or hit the endpoint. One observation beats three paragraphs of inference.
20
+ 6. **Answer "why" honestly.** Look for commit messages, ADRs, or comments. Without them, label the reason as inference.
21
+
22
+ ## Done when
23
+
24
+ - The path is written as a chain with a real location for every hop.
25
+ - Every claim the next step depends on is marked observed (you ran or saw it) or inferred (you read it).
26
+ - Contradictions between the user's description and the code are listed.
27
+ - For a bug: the diagnose branch's red loop exists and the cause is confirmed.
28
+
29
+ ## Anti-patterns
30
+
31
+ | Name | The tell | Fix |
32
+ | --- | --- | --- |
33
+ | File tour | A list of files with one-line summaries | Write the chain of calls instead |
34
+ | Tests as truth | "The test says it works" | Tests show intent; run it to see behavior |
35
+ | Whole-repo read | Opening dozens of files before finding the entry point | Search for the visible string or route first |
36
+ | Fix before repro | Changing code for a bug that was never reproduced | Build the red loop first; reading code to find the repro conditions is fine |
37
+
38
+ ## Handoff
39
+
40
+ For a change, pass the chain, observed facts, contradictions, and open questions to [Impact](../cyc-impact/SKILL.md). For an explanation or lesson, return the model to the parent. For a bug, hand the red loop and confirmed cause onward; do not fix unrelated things you noticed, but list them.
@@ -0,0 +1,53 @@
1
+ # Diagnose a failure
2
+
3
+ Use this branch when something is broken, throwing, wrong, or slow. The rule: **no red loop, no fix.** Read code freely: understanding the code is often how you find the conditions that reproduce the bug. But do not change code to fix a bug you have not reproduced, and treat any theory as unconfirmed until the loop shows it.
4
+
5
+ ## 0. Check the error ledger
6
+
7
+ Search the project's selected shared history (`run next`'s `projectLedgerPath`) and relevant prior run-local histories for the error signature (see the [error ledger skill](../../cyc-error-ledger/SKILL.md)). If an entry exists, start from its recorded attempts and never repeat a failed fix without a new reason.
8
+
9
+ ## 1. Build a red loop
10
+
11
+ A red loop is one command you have already run that shows the user's exact symptom. It must be:
12
+
13
+ - **Red-capable:** asserts the actual symptom, not a nearby one.
14
+ - **Deterministic:** same result every run (or a measured failure rate for flaky bugs).
15
+ - **Fast:** seconds, not minutes, so you can iterate.
16
+ - **Agent-runnable:** no human clicking, unless nothing else works.
17
+
18
+ Try these in order:
19
+
20
+ 1. An existing failing test, or a new failing test at the user's boundary
21
+ 2. A `curl` or HTTP request against the running app
22
+ 3. A CLI invocation with output diffed against a known-good snapshot
23
+ 4. A headless browser script for UI symptoms
24
+ 5. Replaying a captured request, log, or payload
25
+ 6. A throwaway harness that calls the suspect function directly
26
+ 7. `git bisect run` with the loop as the test, when "it used to work"
27
+ 8. A differential loop: run old and new versions on the same input and compare
28
+ 9. A human-in-the-loop script with exact steps and a KEY=VALUE result, as a last resort
29
+
30
+ If you cannot build any loop (the bug only happens in staging, or needs data you cannot access), do not guess at a fix. Continue with what is useful without one: read the code paths, check the error ledger and logs, and narrow the candidates. Then stop and hand off what you learned and ask for one specific thing: access to the environment, a redacted sample of the failing data, or permission to add temporary logging.
31
+
32
+ ## 2. Shrink it
33
+
34
+ Remove inputs, steps, and code until every remaining piece is load-bearing: removing any one turns the loop green.
35
+
36
+ ## 3. Hypothesize before testing
37
+
38
+ Write up to three ranked, falsifiable hypotheses before testing any: "If X is the cause, then changing Y makes the symptom disappear." Show them to the user as you go; don't wait for approval. When the red loop and the evidence point to one clear cause (a stack trace into a null field, a failing assertion on one line), one hypothesis is enough: state the evidence that makes it clear.
39
+
40
+ ## 4. Test one variable at a time
41
+
42
+ Change one thing, rerun the loop, record the result in the error ledger entry, including failures. Tag every temporary log line with a unique marker such as `[DEBUG-7f3a]` so cleanup is one search.
43
+
44
+ ## 5. Stop rules
45
+
46
+ - Two hypotheses disproved: step back, re-read the symptom, and check your loop asserts the right thing.
47
+ - Four disproved: report findings and ask the user before continuing.
48
+
49
+ ## 6. Hand off
50
+
51
+ Give Build the red loop command, the confirmed cause with evidence, and the smallest fix location. The red loop becomes the regression test. If no clean place exists to test the fix, say so: that is a design finding, not something to hide.
52
+
53
+ Clean up: search for your debug marker and delete throwaway harnesses before handing off.
@@ -0,0 +1,87 @@
1
+ ---
2
+ name: cyc-verify
3
+ description: "Prove the requested change works and nothing it touches broke, using checks you actually ran against the current files. Use before accepting any change, when asked \"does it work?\", after a repair, or when a handoff claims success."
4
+ ---
5
+
6
+ # Verify the promised outcome
7
+
8
+ For a new web interface or visual redesign, score the finished page with the [generic-tells sheet](../cyc-design/frontend-design/references/generic-tells.md#score-sheet) at desktop and phone width, then run the [experience review](../cyc-design/frontend-design/references/experience-review.md) against the decision sheet's rejection condition. A theme description, image presence and no clipping cannot establish design quality. If the criterion admits any default page, restore the original ambition before judging; never weaken it to fit the output. Keep a material visual miss unmet despite passing behavior checks. Inspect the main action and access/recovery states separately. Narrow repairs need only applicable checks.
9
+
10
+ For user updates, follow the shared [progress standard](../../docs/response-standard.md#progress-updates): explain which behavior the checks establish and what remains unverified, rather than reporting only pass counts. When a check fails, explain what it revealed and how that affects the next decision.
11
+
12
+ Help the engineer interpret the evidence: connect an important check to the path or consumer it exercises, the defect or rejected case it could detect, and the limit of that conclusion. Explain separately why the implementation fits the intended behavior; semantic review is a judgment, not an executed check. Follow the [engineering understanding standard](../../docs/response-standard.md#engineering-understanding-throughout-the-work).
13
+
14
+ For implementation, verify the changed behavior with executable checks. For advisory Review or Handoff, verify the claims and cited evidence without manufacturing a code change or failing test. An accurate report of a defect can satisfy a review criterion; it cannot satisfy a criterion that the product works. Follow the [handoff contract](../../docs/skill-contract.md) for evidence labels.
15
+
16
+ Apply the project's applicable `code-standards.md` and the relevant [code standards](../../docs/engineering/code-standards.md) to the actual diff and callers. Check information-bearing comments, justified assertions/suppressions, failure outcomes and useful structure; preserve legitimate exceptions. Record tool results separately from this semantic judgment. Reading the standards, a comment search or an unchecked checklist does not prove compliance.
17
+
18
+ ## The core loop
19
+
20
+ 0. **Use applicable recipes automatically.** Run `node <cli> recipe list --run <ID>` or `--path <affected paths>`. Read selected expected outcomes, prerequisites/effects and any relevant manual steps in `docs/context/verify-recipe.md`. Execute applicable authorized supplementary checks with `recipe run --recipe <ID>`; explain unavailable prerequisites or scope boundaries. Entries with `configuredCommandIds` are already owned by final configured verification: defer those to step 5 and cite that actual result, avoiding duplicate final execution. Old recipe receipts are diagnostic history. When nothing matches, discover the needed check through [references/recipe.md](references/recipe.md). Retain authorized reusable steps before final verification; document/CLI work does not require a browser recipe.
21
+ 1. **Build the check matrix first.** One row per acceptance criterion and one row per consumer named in the plan (or the [impact map](../cyc-impact/SKILL.md) in the detailed chain). Each row names the check that would show it *red* if it were broken. A row with no red-capable check is a gap; record it now, not at the end.
22
+ 2. **Establish the appropriate test proof.** For features and bugs, check that the regression test fails on the original code for the intended reason and passes on the candidate. For refactors, characterization tests must pass on both. In a managed run, `run finish` runs `prove-red` when the proof is missing or outdated; run `run prove-red` yourself for an earlier check, and inspect its receipt. Do not manually revert shared working files. New runs retain permitted originals through Git and/or bounded run-start capture, including plain/no-commit projects; older runs cannot gain a capture after edits. Missing or changed needed originals refuse proof. Use a quiescent working folder: the project operation lock coordinates controllers, while external edits are checked only at boundaries. On a conflict or interruption, use `run recover`, preserve current files/locks and the recorded candidate backup, and compare deliberately; never clear locks, overwrite another writer or reset a halted run to force proof. See [ownership and recovery](../../docs/onboarding-recovery.md#proof-conflicts-and-interrupted-ownership). The aggregate proof establishes that at least one new test detects changed behavior, not that every test does. Existing-behavior guards may stay green. For advisory claims, inspect primary evidence and reproduce findings where feasible; no manufactured red test is required. If proof is unavailable, record the actual limitation and alternative evidence through the supported assessment exemption; never describe it as proven or disguise testable behavior as untestable. See [run-start originals](../../docs/runtime.md#run-start-originals).
23
+ 3. **Run the journey, not only the unit.** Run the recipe's checks that apply to this change first. For anything the recipe doesn't cover, pick the tightest loop that exercises the real path, in this order of preference:
24
+ 1. the project's existing test for that behavior
25
+ 2. a new focused test at the boundary the user touches
26
+ 3. a script or CLI call with a snapshot or diff of output
27
+ 4. an HTTP request (`curl`) against the running app
28
+ 5. a headless browser such as Playwright for UI journeys (click, reload, check again)
29
+ 6. a human-in-the-loop step, as a last resort, with exact instructions and the expected observation
30
+ 4. **Hit the edges the change created.** Old saved data, repeat actions (clicking twice), unknown IDs, empty state, and the error path. For a guard, show a rejected case, not only an allowed one. For operations that recreate records, apply the [preservation contract](../../docs/engineering/failure-handling.md#preserve-records-when-an-operation-recreates-them): inspect stored fields and relevant access metadata beyond the UI projection, through success and failure recovery. Check that the fixture would detect losing them.
31
+
32
+ Tie each original user criterion to a decisive check/scenario and the observed result, even when several share a suite command. In red proof, distinguish an assertion of the original defect from a missing newly introduced API or module-load failure. The latter may show a new dependency is absent; it does not establish the intended old-behavior failure. Keep useful genuine red assertions and state their limits.
33
+ 5. **Run configured checks on the final candidate.** For step-by-step execution use `run verify --run <ID>`; the fast implementation route's `run finish` executes these checks itself. Do not run both on an unchanged candidate merely to duplicate a receipt. Advisory routes without configured checks use clearly labeled inspected evidence. Focused checks give fast feedback; final checks cover the affected behavior.
34
+ With `evidenceVersion: 1`, fill `criterionChecks` for every original criterion/clause. Use a named scenario and actual observation, configured command ID, `receipt: "current-verification"`, `result: "passed"`, and `origin: "agent-reported"`. Missing or unavailable required checks stay unverified and cannot pass. For non-exempt red proof, run `prove-red` and fill `proofReview` against its failure IDs: `behavioral`, `new-interface`, `setup`, or `unclassified`, with a reason and an existing observable boundary for behavioral cases. A bug-fix proof needs a decisive behavioral case; a feature may demonstrate an absent new interface. Error type alone cannot decide the category. Review receipts must come from capture before the review and record afterward; later edits stale the whole-source capture. See the [evidence record examples](../../docs/work-assessments.md#versioned-evidence-records).
35
+ 6. **Fill the matrix with results.** Each row: passed (with the command and what you saw), failed (with output), or unverified (with why, such as no browser access). Model review of code goes in its own labeled row and never turns a row green.
36
+ 7. **Record semantic review separately.** Trace the important state, shared invariant, consumers and relevant failure paths in the actual diff; identify where a likely next change belongs. Review intent, conventions and the [engineering principles](../../docs/principles.md), using the [finding adjudication guidance](../../docs/code-quality.md#review-findings-before-turning-them-into-edits) for consequential diffs. For changed business rules/transitions, inspect the owner and callers using the [domain examples](../../docs/engineering/domain-design.md); for rejection, I/O or partial effects, inspect failure identity, committed/unknown state and retry safety using the [failure examples](../../docs/engineering/failure-handling.md). Apply their stated contracts and exceptions rather than requiring their exact code shape. Show the legitimate trigger or concrete maintenance consequence before requiring a repair; check whether a proposed simplification removes policy duplication or merely moves it. Resolve or dismiss findings with evidence, and keep unresolved required findings open and blocking. New implementation runs require the [Verify assessment](../../docs/work-assessments.md#verify-executable-evidence-plus-semantic-judgment), with a passing check for every Scout consumer and newly discovered consumer. Label self-review; extra reviewers depend on risk. If final context/ledger edits change source, rerun checks before recording the assessment.
37
+
38
+ ## Done when
39
+
40
+ Applicable checks have captured evidence, every criterion and affected consumer has a result, and every passing claim cites evidence for the current file state. Changed behavior has the required red/green proof; refactors have preservation evidence; exemptions and advisory observations remain labeled. If a required criterion is failed or unverified, do not record a passing stage: route it using the table below. A review can report defects successfully when its criteria ask for supported findings rather than a working product.
41
+
42
+ **Suspect the observation before the system.** When a result surprises you, first check that the check itself measures the right thing (right port, right build, right data).
43
+
44
+ **Pre-existing failures.** Normal runs do not run a baseline before editing. A project may explicitly enable `verification.baseline: true` for diagnostic background measurements; do not wait for them. For bug fixes and features without one, the proof's control run measures every check on the run-start code. An unrelated check that already failed there can be accepted with a reason, in `run finish` (`acceptFailures`) or with `run accept-failure`. It no longer blocks completion while it fails exactly as it did then, and another check passes. "Exactly" means the same exit code, the same output lines apart from timings, and no file you changed named in its output.
45
+
46
+ For a TAP (`node --test`, `tap`), mocha, or jest suite, "exactly" means all of these, also for output longer than the 32,000 characters kept, provided a test in it already failed at the run start:
47
+ - no test fails that did not fail then;
48
+ - every old failure has the same error, and its stack does not run through source you changed;
49
+ - no new non-test line appears. A failed verification lists `failedAtRunStart`: decide for each check whether it is unrelated (accept it) or caused by your change (fix it). Do not retry unchanged. Name it in the reply as a pre-existing failure. New regressions can hide inside the same command. Any of these still leaves verification unverified, with the cause in `acceptedFailuresThatChanged`:
50
+ - a new or lost line;
51
+ - a different exit code or a hang;
52
+ - truncated output;
53
+ - a check that prints nothing. Report a blocked handoff when the failure cannot be repaired within scope. Do not change configuration or drop tests mid-run to obtain success.
54
+
55
+ ## Anti-patterns
56
+
57
+ | Name | The tell | Fix |
58
+ | --- | --- | --- |
59
+ | Green-by-reading | "The logic looks correct" with no command run | Run something that could fail |
60
+ | Tautological test | The expected value is computed the same way the code computes it | Assert a literal known-good value |
61
+ | Hollow test | It would still pass if every imported function returned `undefined` | Assert on real output, not on mocks or fixtures |
62
+ | Wrong surface | Checked the API when the user asked about the page | Verify where the user sees the behavior |
63
+ | Unit-only for a journey | Component test passes; nobody reloaded the page | Add the journey check from step 3 |
64
+ | Retry until green | Rerunning a flaky test until it passes | Diagnose the flake or mark unverified |
65
+ | Stale evidence | Result is from before the last edit | Rerun after the final change |
66
+
67
+ ## Routing failures
68
+
69
+ Read `run recover --run ID` after a verification failure or interruption. Failed receipts remain diagnostic even when current verification has been invalidated. Describe the specific failed behavior, the cause only as far as the evidence supports it, and the next justified action. Executable-not-found and timeout observations do not by themselves diagnose the application. Use the existing review and receipt when teammate help is needed; never automatically message someone or start a new budget after exhaustion. See [recovery guidance](../../docs/onboarding-recovery.md).
70
+
71
+ In fast playbooks (scout → build → verify → deliver), Frame, Impact, and Design map to Scout. Before an authorized implementation repair, use `run retry --run <ID> --stage build --reason "<finding>"`, record the repaired artifacts, and verify again. Return to Scout when a missed consumer or invalid approach changes the plan. Advisory routes report the finding unless repairs are authorized. Changes after a passing Verify handoff require returning to Verify with fresh checks and semantic review before delivery; implementation repairs return through Build first.
72
+
73
+ | What you saw | Send it to |
74
+ | --- | --- |
75
+ | Right design, wrong code | [Build](../cyc-build/SKILL.md) with the failing command |
76
+ | A consumer nobody mapped broke | [Impact](../cyc-impact/SKILL.md), then affected work |
77
+ | The approach cannot meet a criterion | [Design](../cyc-design/SKILL.md) with the disproved assumption |
78
+ | The criterion measures the wrong thing | [Frame](../cyc-frame/SKILL.md), keeping the failed result on record |
79
+ | Missing access or service | Blocked, naming the smallest thing the user can provide |
80
+
81
+ Never edit thresholds, skip tests, or loosen criteria to pass. When a recipe check fails, fix the cause and rerun the whole applicable set: this is the loop, and it runs without the user pointing anything out.
82
+
83
+ **Retain missing checks without changing the contract.** Save proposed checks in `.cyc/runs/<runId>/proposed-checks.json` when durable recipe edits are outside scope. Never edit `.cyc/config.json` during an active run. Promote authorized proposals in a subsequent scoped change and verify that change; edits after completion are not covered by the completed run's evidence. Do not ask for permission again when the user already authorized that follow-up.
84
+
85
+ ## Example
86
+
87
+ Homework "mark finished": the matrix has rows for the click, the active list, the remaining count, reload persistence, old saved records without a `finished` field, and double-marking. The new persistence test is first run against the unmodified save code and fails, proving it can catch the bug. After the fix it passes, and a reload check in the browser confirms it. The row for cross-device sync stays out of the matrix because it was never requested.