Compare commits

..
Author SHA1 Message Date
Matt PocockandClaude Opus 4.8 fa460cbf09 prototype: drop the vestigial "let it go"
Rule 4 is about skipping polish, not the prototype's fate; the trailing
"then let it go" was a leftover from the old delete-it framing and now
misreads as discard, contradicting capture-as-primary-source. Cut it,
and rename LOGIC step 7 off "let go".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-10 11:35:29 +01:00
Matt PocockandClaude Opus 4.8 0375c88bfb prototype: collapse the when-done section into rule 6
The "keep it as a primary source" section restated rule 6 and was
padded with no-ops. Fold the one extra bit (capture the answer) into
rule 6 and delete the section: capture the prototype as a primary
source on a throwaway branch, pointer on the issue.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-10 09:49:44 +01:00
Matt PocockandClaude Opus 4.8 371b9c9c94 prototype: capture the prototype, don't dispose of it
Reframe the artifact handling as capturing the prototype somewhere out
of main — a throwaway branch — with a context pointer to it left on the
implementation issue, instead of "disposing" of it. The main branch
still keeps only the validated decision.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-10 09:39:52 +01:00
5 changed files with 7 additions and 17 deletions
+1 -1
View File
@@ -2,4 +2,4 @@
"mattpocock-skills": minor
---
Reword how the **`prototype`** skill lets go of its artifacts around a single idea: **the prototype is a primary source**. Rather than being deleted once it's answered its question, the prototype is kept as runnable evidence on a throwaway branch (`prototype/<name>`) linked from the relevant issue, never merged, so the main branch keeps only the validated decision. The answer (verdict + question) is still captured durably in an issue/ADR/commit.
Reword how the **`prototype`** skill handles its artifacts around a single idea: **the prototype is a primary source**. Rather than being deleted once it's answered its question, the prototype is captured as runnable evidence on a throwaway branch (`prototype/<name>`) out of main, with a context pointer to it left on the implementation issue — so the main branch keeps only the validated decision while the exploration stays findable. The answer (verdict + question) is still captured durably in an issue/ADR/commit.
+1 -1
View File
@@ -35,7 +35,7 @@ Picking the wrong branch wastes the whole prototype, so the question comes first
A finished prototype leaves two things. The **answer** — the verdict plus the question it settled — is what you capture durably (a commit message, an ADR, an issue). The **prototype itself is a primary source** — the runnable evidence the answer came from.
The prototype doesn't belong in the main repo: no tests, no error handling, nothing to maintain. But that's not a reason to destroy it. Once the answer is captured, fold any validated decision into the real code, then move the prototype onto a throwaway branch linked from the relevant issue — never merged. The main branch stays clean; the raw exploration stays one click away for anyone who wants to re-run it. A prototype left rotting in the main branch has outlived its purpose — a prototype kept as a primary source on a side branch hasn't.
The prototype doesn't belong in the main branch: no tests, no error handling, nothing to maintain. But that's not a reason to destroy it. Once the answer is captured, fold any validated decision into the real code, then capture the prototype on a throwaway branch — out of main, never merged — and leave a context pointer to it on the implementation issue. The main branch stays clean; the raw exploration stays one click away for anyone who wants to re-run it. A prototype left rotting in the main branch has outlived its purpose — a prototype captured as a primary source on a side branch hasn't.
## Where it fits
+2 -2
View File
@@ -66,9 +66,9 @@ If the host project has no task runner, just put the command at the top of the p
Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve.
### 7. Capture the answer and let go
### 7. Capture the answer and the prototype
Once the prototype has answered its question, capture the answer and dispose of the prototype the way the [SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the TUI shell rides along to the throwaway branch that keeps the prototype as a primary source.
Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the TUI shell rides along to the throwaway branch that keeps the prototype as a primary source.
## Anti-patterns
+2 -12
View File
@@ -21,16 +21,6 @@ The two branches produce very different artifacts — getting this wrong wastes
1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast and then let it go.
4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
6. **Let go of it when done.** Fold any validated decision into the real code, then keep the prototype itself as a **primary source** committed to a throwaway branch linked from the relevant issue, never merged to main (see _Keep it as a primary source_ below). The main branch keeps only the validated decision.
## When done: keep it as a primary source
Two things come out of a finished prototype.
- **The answer** — the verdict plus the question it settled — is what you capture durably: an issue comment, an ADR, or a commit message. If the user is around, that's a quick conversation; if not, leave a placeholder (a `NOTES.md` next to the prototype) so the verdict can be filled in before you move the code.
- **The prototype itself is a primary source** — the runnable evidence the answer came from. With no tests and no maintenance story it doesn't belong in the main repo, but that's not a reason to delete it. Once the answer's captured, get the prototype out: commit it to a throwaway branch (e.g. `prototype/<name>`), push it, and link that branch from the relevant issue. Never merge it. The main branch keeps only the validated decision folded into real code; the raw exploration stays on the branch, one click away for anyone who wants to re-run it.
This is distinct from _absorbing_: lifting a validated reducer, state machine, or UI direction into the real module keeps the **decision**, not the prototype. The throwaway branch is what keeps the prototype as a primary source.
6. **Capture it when done.** Fold any validated decision into the real code, then capture the prototype itself as a **primary source**: commit it to a throwaway branch, out of main, and leave a context pointer to that branch on the implementation issue. Capture the answer too — the verdict and the question it settled — in the issue or a commit. The main branch keeps only the validated decision.
+1 -1
View File
@@ -97,7 +97,7 @@ Surface the URL (and the `?variant=` keys). The user will flip through whenever
### 6. Capture the answer and clean up
Once a variant has won, capture the answer — which variant and why — and dispose of the prototype the way the [SKILL](SKILL.md) describes. Fold the winner into the real code and get the rest out of the main branch:
Once a variant has won, capture the answer — which variant and why — then capture the prototype the way the [SKILL](SKILL.md) describes. Fold the winner into the real code and move the rest onto the throwaway branch, not into main:
- **Sub-shape A** — fold the winner into the existing page; drop the losing variants and the switcher from main.
- **Sub-shape B** — promote the winning variant to a real route; drop the throwaway route and the switcher from main.