Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

docs: preserve validated spike behavior in planning and implementation skills

David Zhang7e4f38ae42b8
diff --git a/.agents/skills/implement-spec/SKILL.md b/.agents/skills/implement-spec/SKILL.md
index 2fb3d6e..3440bb9 100644
--- a/.agents/skills/implement-spec/SKILL.md
+++ b/.agents/skills/implement-spec/SKILL.md
@@ -6,8 +6,8 @@ description: Implement an existing spec through committed passes. Use for long o
# Implement Spec
Build the active spec to completion, one reviewable pass at a time. The spec is
-the source of truth, but the architecture is allowed to improve when the code
-teaches you the plan is stale.
+the implementation plan; user constraints and accepted experimental evidence
+remain binding when the architecture changes.
A pass (usually one slice) is a **commit checkpoint, not a stopping point.** The
job is the whole spec — every slice, every global TODO — not the first green
@@ -27,6 +27,7 @@ depends on prior work.
Load any skills named by the spec. Identify the current pickup point, global
TODOs, required gates, and what must stay green. If a multi-slice spec lacks
a live handoff prompt, add one before the first pass ends.
+ For a validated spike, apply **Preserve the winner** below before editing.
2. Reconcile the plan with the current code. If the slice would preserve a
development-only shim, duplicated type, weak wrapper, or obsolete path,
replace it with the simpler architecture and update the spec handoff.
@@ -49,9 +50,10 @@ depends on prior work.
5. **Review the change list and clean up after every pass, before committing.**
Read `git status`/`git diff --stat` line by line and account for every path:
one-off probes, shot scripts, scratch files, `nohup.out`, ad-hoc screenshot
- dirs, and SPIKE/debug notes never enter a commit — scratch stays out of the
- tree; review evidence belongs in the spec's `assets/`; anything else gets
- deleted. A file you can't name the durable purpose of does not ship.
+ dirs, and disposable SPIKE/debug notes never enter a commit — scratch stays
+ out of the tree. Preserve frozen references, fixtures, and research evidence
+ in the project's reference or spec assets area. A file without a durable
+ purpose does not ship.
Delegated agents leak these; the integrating reviewer re-checks the merged
tree with the same eye.
@@ -129,6 +131,22 @@ depends on prior work.
by verdict, ranked least-confident-first, every entry ELI5 and standalone.
*Then* close the spec with [close-spec](../close-spec/SKILL.md).
+## Preserve the winner
+
+- Read the frozen winning code, configuration, prompts/skills, and evidence.
+ Preserve actual behavior, including quirks whose contribution is unknown.
+ A rewritten spec or cleaner design does not supersede measured results.
+- Port first; experiment separately. Give delegates the same reference and
+ constraints. Record user-required differences; validate other behavioral
+ changes against the winner before adopting them.
+- Prove parity through the production entry point with matched inputs and
+ controlled external responses. Compare computed requests, decisions, complete
+ outputs, and relevant recovery paths—not just templates or component tests.
+ Normalize only documented intentional differences. Run these cheap checks
+ before costly confirmation, retaining the original quality gates.
+- Missing parity evidence means unfinished. Preserve the reference and continue
+ independent work rather than declaring equivalence.
+
## Rules
- **Delegate independent work to subagents so passes run in parallel.** The
diff --git a/.agents/skills/write-spec/SKILL.md b/.agents/skills/write-spec/SKILL.md
index 34ed051..64a0f04 100644
--- a/.agents/skills/write-spec/SKILL.md
+++ b/.agents/skills/write-spec/SKILL.md
@@ -1,6 +1,6 @@
---
name: write-spec
-description: Break large features into independently verifiable, human-reviewable slices under specs/<feature>/. Use for risky or multi-step feature work that needs upfront questioning, API seams, browser-playable checkpoints, HTML visualizations, screenshot gates, staged implementation plans, recursive fog-of-war reslicing, or proactive research into reference implementations/best practices before slicing. Pairs with your project's verification harness and screenshot gates (the browser checkpoints), [refactor-clean](../refactor-clean/SKILL.md) (review the materialized spec so the plan describes one-owner architecture, not the feature bolted on), [screenshot-critique](../screenshot-critique/SKILL.md) and [compare-screenshots](../compare-screenshots/SKILL.md) (the visual gates), and a code-review pass (audit each slice before it lands).
+description: Break large features into independently verifiable, human-reviewable slices under a feature directory in specs/. Use for risky or multi-step feature work that needs upfront questioning, API seams, browser-playable checkpoints, HTML visualizations, screenshot gates, staged implementation plans, recursive fog-of-war reslicing, or proactive research into reference implementations/best practices before slicing. Pairs with your project's verification harness and screenshot gates (the browser checkpoints), [refactor-clean](../refactor-clean/SKILL.md) (review the materialized spec so the plan describes one-owner architecture, not the feature bolted on), [screenshot-critique](../screenshot-critique/SKILL.md) and [compare-screenshots](../compare-screenshots/SKILL.md) (the visual gates), and a code-review pass (audit each slice before it lands).
---
# Write Spec
@@ -89,6 +89,8 @@ whole feature is done.
standard, visual target, or performance pattern. Capture the discovered
source/repo/article/paper links in the spec and turn any exemplar into a
reproduction spike before a porting slice.
+ If prior experiments already established an accepted approach, apply
+ **From research to implementation** below before drafting alternatives.
3. **Draft in parallel:** for a multi-slice feature, spawn **at least three
independent subagents** to draft the whole plan — fresh context each, a git
worktree apiece if they must run or build to validate, otherwise have them
@@ -182,6 +184,23 @@ whole feature is done.
resume from the first new slice. Then continue. Reslicing is progress, not
failure.
+## From research to implementation
+
+Freeze the accepted spike's runnable code, dependencies, configuration,
+inputs, prompts/skills, and evidence by immutable identity. Inspect what it
+actually does; option names and summaries are not proof of behavior.
+
+Map **proven behavior → evidence → owning slice → parity gate** in the spec.
+Give every drafter this contract and the limits of the findings. Separate
+user-required differences from untested proposals; cleanup must not silently
+redesign the winner.
+
+Plan an early production-entry-point comparison against the frozen reference
+with matched inputs and controlled responses. Check computed requests,
+decisions, and complete outputs; name permitted differences. Every preservation
+row needs an owner and a check. Run parity before expensive confirmation and
+retain the original quality gates.
+
## Plan Folder
Use `specs/<feature>.md` only for a small, single-slice problem. Large