| name | yegor-spikes |
| description | Research/scope spikes for large or fuzzy issues. Run a bounded ≤60min investigation session to discover code sites, current state, open questions, and ROI before writing any @todo puzzle. Use when a GH issue is too vague or too large to add a meaningful @todo — scope it first, puzzle later. |
| version | 0.1.0 |
| last_reviewed | 2026-05-27T00:00:00.000Z |
Yegor Spikes — Scope Before You Puzzle
When you can't place a @todo because the code site is unknown, the scope is fuzzy, or the problem is too large to fit in ≤60m, run a spike first. A spike is a ≤60m research and documentation session whose output is the information needed to write real puzzles.
Triggers
- A GH issue exists but no one knows which file to put the
@todo in
- Estimate for the issue is clearly > 60min with no obvious decomposition
- The issue says "investigate", "assess", "figure out", or "research"
- Multiple legacy issues exist with no
@todo markers yet
- A feature is requested but its implementation approach is unknown
Spike anatomy
A spike produces a scope comment on the GH issue containing:
- Current state — what the code already does today (file:line citations)
- Gap — what it doesn't do that the issue asks for
- Key code sites — the exact files and line numbers affected
- Open questions — anything still ambiguous after investigation
- Perceived ROI — is the work worth doing? Is there a simpler alternative?
- Closure recommendation — one of:
- "Ready to decompose into N puzzles" (proceed to architect mode)
- "Defer — low ROI, no concrete trigger"
- "Close — already resolved by other work"
Spike rules
- Hard time limit: 60 minutes. If you don't have enough information, write what you have and flag remaining questions.
- Output is documentation, not code. You may read code, run tests, and consult the oracle — but the deliverable is the scope comment, not implementation.
- One spike per issue. Don't open multiple spike tickets for the same issue — extend the scope comment instead.
- Spike closes only when its recommendation is acted on. If you recommend decomposition, close after the N child issues are created.
GH issue format for a scope/spike ticket
## Purpose
Spike to scope [original issue #N]. Output: bounded @todo(s) or defer/close decision.
## Current state
[what exists today, with file:line citations]
## Gap
[what the issue asks for that doesn't exist]
## Key code sites
- `path/to/file.js:line` — [why it's relevant]
## Open questions
- [anything still ambiguous]
## Perceived ROI
[High/Medium/Low — justify briefly]
## Recommendation
[ ] Decompose into N puzzles [ ] Defer [ ] Close
Rules for Claude
When a large issue has no @todo:
- Propose a spike instead of placing a speculative
@todo.
- "This is too large/fuzzy to puzzle directly. Want me to run a 30-minute scope session and document the findings as a GH comment?"
When running a spike:
- Read the relevant code, grep for call sites, check existing tests and docs.
- Write findings directly into the GH issue comment (per
yegor-tickets — all decisions in the tracker).
- End with a concrete recommendation.
When the spike concludes:
- If decomposing: enter architect mode, write the design, open N child issues with @todos.
- If deferring: close the spike issue with justification; leave the parent open with a "deferred pending X" comment.
- If closing: close both spike and parent with the "already resolved" explanation.
Pitfalls
- Don't turn a spike into implementation work. If you catch yourself writing code, stop.
- Don't run a spike for work you already understand. If you know the code site, write the
@todo directly.
- Don't leave a spike open indefinitely. If the recommendation is "defer", close it.
Cross-references
yegor-pdd — spikes produce the inputs that @todo puzzles need.yegor-architect — after a spike, architect mode produces the actual design.yegor-microtasks — spikes are themselves ≤60m micro-tasks.yegor-tickets — spike findings land as issue comments, not in chat.
