| 1 | --- |
| 2 | name: cw-slice |
| 3 | description: "Use before writing code for any Codewhale feature, upgrade, or refactor: find the existing owner of the behavior, bound the change to one reviewable slice, and fix the evidence bar before you start." |
| 4 | --- |
| 5 | |
| 6 | # cw-slice |
| 7 | |
| 8 | The expensive mistake in this repo is not a bad implementation — it is a second |
| 9 | implementation. A new `model_*`, `*_config`, `provider_*`, or "bridge" module |
| 10 | beside the one that already does the job ships two systems and a comment that is |
| 11 | no longer true. This skill is the ponytail ladder's rung 2 with commands |
| 12 | attached: **find the thing that already exists, then edit it.** |
| 13 | |
| 14 | Stage 2 of the loop: [cw-orient](../cw-orient/SKILL.md) → **slice** → |
| 15 | [cw-gates](../cw-gates/SKILL.md) → [cw-dogfood](../cw-dogfood/SKILL.md) → |
| 16 | [cw-land](../cw-land/SKILL.md) → [cw-handoff](../cw-handoff/SKILL.md). |
| 17 | |
| 18 | ## When to use |
| 19 | |
| 20 | - Any feature, upgrade, refactor, or "make X work like Y" request. |
| 21 | - Before creating a new module, trait, config struct, or command. |
| 22 | - When a plan or issue tells you to build something and you have not yet |
| 23 | confirmed it does not already exist. |
| 24 | |
| 25 | ## Workflow |
| 26 | |
| 27 | 1. **Walk the ladder before opening an editor.** Stop at the first rung |
| 28 | that answers: |
| 29 | 1. Does this need to exist? → skip it. |
| 30 | 2. Already in this codebase? → reuse it. |
| 31 | 3. Stdlib does it? → use it. |
| 32 | 4. Native platform feature? → use it. |
| 33 | 5. Installed dependency? → use it. |
| 34 | 6. One line? → one line. |
| 35 | 7. Only then: the minimum that works. |
| 36 | |
| 37 | The ladder runs *after* reading the code, never instead of it. A short diff |
| 38 | written without reading the call sites is a guess, not a small change. |
| 39 | State the rung only when the choice isn't obvious from the diff itself. |
| 40 | |
| 41 | 2. **Grep for the predecessor.** This is the step that gets skipped and the one |
| 42 | that costs the most: |
| 43 | ```bash |
| 44 | grep -rn "<the concept, in the words the code would use>" crates --include='*.rs' | head -40 |
| 45 | ls crates |
| 46 | grep -rln 'model_\|_config\|provider_' crates/*/src --include='*.rs' | head -30 |
| 47 | ``` |
| 48 | Search behavior and symbols, not just filenames. If you find an owner, edit |
| 49 | it. If you are still adding a new layer, its module doc must name the |
| 50 | predecessor it replaces — otherwise you are editing the wrong file. |
| 51 | |
| 52 | 3. **Check the contracts you are about to walk into.** One of these is |
| 53 | guard-tested, the rest are convention — either way, move them with their |
| 54 | code, not around it: |
| 55 | - One turn loop: `crates/tui/src/core/engine/turn_loop.rs`, guarded by |
| 56 | `crates/core/tests/single_turn_loop.rs`. A second loop fails the guard; |
| 57 | changing the shape means changing the guard with it. |
| 58 | - One base prompt: `BASE_PROMPT` in `crates/tui/src/prompts/text.rs`. |
| 59 | - The subagent tool is `agent`; `agent_open` / `agent_eval` / |
| 60 | `agent_close` / `delegate_to_agent` are removed surfaces. If the shape |
| 61 | must move, move the code and add the guard test that judges the new |
| 62 | shape — the convention is not a fence around the area. |
| 63 | - The system prompt + tool catalog are a session-pinned KV-cache prefix |
| 64 | (`docs/CACHE.md`). Any new session-context contributor must state its cache |
| 65 | effect — frozen prefix vs. append-only history. Never splice a volatile |
| 66 | fact into the prefix. |
| 67 | - `crates/tui/src/core/` is a module inside the TUI crate. `crates/core` is a |
| 68 | different crate that runs no turns. Do not confuse them. |
| 69 | - Repeatedly misidentified as dead, verify consumers before removing: |
| 70 | `tui/src/context_budget.rs`, `tui/src/model_registry.rs`, |
| 71 | `tui/src/prompt_zones.rs`, `tui/src/tools/remember.rs`, `config/src/route/`. |
| 72 | |
| 73 | 4. **Read the scoped guidance for the files you will touch.** `crates/tui/AGENTS.md` |
| 74 | owns the UI contracts (one owner per fact, `codewhale_palette::grammar` semantics, typed |
| 75 | state enums, toast routing, `tr(locale, MessageId::...)` for user prose). |
| 76 | `crates/tui/locales/AGENTS.md` owns string changes. `web/AGENTS.md` owns the |
| 77 | site. `docs/MOTION_CONTRACT.md` owns motion. Design law lives in |
| 78 | `docs/design/`, not in a prototype file someone left in a sibling directory. |
| 79 | |
| 80 | 5. **Bound the slice.** One coherent change, reviewable in one sitting, that |
| 81 | leaves the tree building and green. Two rules keep slices honest: |
| 82 | - **An abstraction must delete caller code.** If adopting it is pure |
| 83 | obligation — required methods, no default bodies that do work — it will be |
| 84 | built, adopted once, and abandoned. Don't build it. |
| 85 | - **Migrate the last consumer, or do not start.** Framework, one caller, |
| 86 | ticket the rest, silence the warning: that is how two systems ship. If the |
| 87 | migration will not fit in this slice, narrow the slice — never the adoption. |
| 88 | |
| 89 | 6. **Fix the evidence bar now, not after.** Decide before writing code what will |
| 90 | prove this works, and write it into your plan: |
| 91 | - the focused test or existing check that covers the behavior |
| 92 | (`scripts/dev-test.sh --list` maps an area to its fastest invocation); |
| 93 | - whether the change is visible enough to need [cw-dogfood](../cw-dogfood/SKILL.md); |
| 94 | - whether it is cross-cutting enough to need the full sweep in |
| 95 | [cw-gates](../cw-gates/SKILL.md). |
| 96 | |
| 97 | 7. **Write the implementation first.** Code first, then tests — this repo does |
| 98 | not practice TDD, and that overrides any skill that says otherwise. Build it, |
| 99 | prove it runs, then add or adjust tests to cover what you actually built. A |
| 100 | regression test written after the fix still has to be shown failing without |
| 101 | the fix. |
| 102 | |
| 103 | ## Red flags / don't |
| 104 | |
| 105 | - Don't add a module that "bridges", "mirrors", "stages", or "wraps" something |
| 106 | that already exists without naming that thing in the module doc. |
| 107 | - Don't fork a singleton (turn loop, base prompt, delegation axis, |
| 108 | lifecycle system) without moving its guard test and consumers with it. |
| 109 | The repo has one of each on purpose; a silent second one is the failure |
| 110 | mode, not the refactor. |
| 111 | - Don't write tests first. Don't add tests by default either — add one when it |
| 112 | cheaply protects safety, data integrity, protocol compatibility, or a |
| 113 | reproduced regression. |
| 114 | - Don't contort production code to keep a brittle assertion green. A test that |
| 115 | only encodes old behavior is evidence, not a veto: change it with the code. |
| 116 | - Don't cut trust-boundary validation, data-loss handling, security, or |
| 117 | accessibility to make a diff shorter. Brevity is never a reason to drop a guard. |
| 118 | - Don't leave a `#[allow(dead_code)]` behind as the cost of an incomplete |
| 119 | migration — `scripts/check-dead-code-budget.py` is the running receipt. |
| 120 | |
| 121 | ## Output |
| 122 | |
| 123 | Default shape before the first edit — compress when trivial (a one-line |
| 124 | change gets a one-line note, not four bullets): |
| 125 | |
| 126 | - which rung of the ladder you stopped at and why; |
| 127 | - the existing owner you found (`path/to/file.rs:line`), or the predecessor |
| 128 | your new module names; |
| 129 | - the bounded slice, in one sentence; |
| 130 | - the evidence bar you will meet, chosen in advance. |
| 131 |