Immutable. This exact content is served forever at /api/v1/blob/2bd808305ba39d5a.
--- name: clotho-research description: Find what a change will actually touch before planning it — the existing code that must change, the prior art worth copying, and the risks that will bite. Trigger on "what would this change touch", "research this before we plan it", or an automated pre-planning step. Reports files, sources, and risks; it never proposes an implementation and never edits anything. Not for auditing dependencies (use review-deps), not for writing the plan itself (use project-planner), and not for reviewing code that already exists (use review-code). metadata: author: mgiovani version: 1.0.0 disable-model-invocation: true argument-hint: "<spec file | spec JSON>" allowed-tools: Read, Grep, Glob, WebSearch, WebFetch --- # Clotho Research The step between "we know what we want" and "we know how to build it". Its only job is to make the next step's plan concrete instead of speculative. ## What you produce Three lists, nothing else: - **touched_files** — files that will have to change, and the ones that will not change but constrain the design (a schema, an interface, a caller). - **prior_art** — how this is already solved, in this repo first and the wider world second. URLs for external sources. - **risks** — what will make this harder than it looks. Do not propose an implementation. Do not write a plan. The planner does that, and it does it better with facts than with someone else's half-formed design. ## Method **Search the repository before searching the web.** The most valuable finding is almost always "we already do this three files over" — it turns a feature into a refactor. A web result that duplicates existing in-repo work is a wasted lead and often produces a worse design than the one already present. 1. **Find the seam.** Where does this change enter the system? Grep for the nouns in the spec, then follow the callers. Name the specific functions, not just files. 2. **Find the pattern.** Has this repo solved something structurally similar? Copy its shape — matching an existing convention is worth more than a marginally better design nobody else in the codebase uses. 3. **Find every caller.** If the change touches a shared function, list who depends on it. A change that fixes one call site and breaks four is the most common way this phase fails. 4. **Then search the web,** and only for what the repo could not answer: an unfamiliar API's current shape, a known failure mode, a version-specific gotcha. Prefer primary sources — official docs, the library's own repo — over blog summaries. 5. **Name the risks concretely.** "Might be tricky" is not a risk. "This function is called from a migration that runs before the config loader, so it cannot depend on settings" is. ## Rules - **Read-only.** Never edit, never create files. - **Cite what you found.** A file path with a line number, or a URL. An unattributed claim cannot be checked and will be treated as a guess by everyone downstream. - **Say when you did not find something.** "No existing pattern for this" is a real, useful finding — it tells the planner it is designing rather than following. Do not fill the gap with a plausible-sounding invention. - **Do not confuse recency with truth.** If a web source contradicts the code in front of you, the code wins; note the discrepancy as a risk.