--- name: eigenspec description: Deconstruct a (possibly rough/typo'd) prompt or idea into a structured spec — requirement eigenvectors, an ordered task DAG, detected contradictions, and clarification questions — before any code is written. Use when the user types /eigenspec, or asks to spec/decompose/PRD an idea or feature, or says "build X" for anything non-trivial and you want spec-first rigor. --- > **eigenspec — idea → structured spec · Eigen Hitchens · free skill, v1.11.0** > Drop this file into your Claude Code `skills/` folder and invoke it by name. > License: MIT · https://eigenhitchens.com/tools/eigenspec # eigenspec — idea → structured spec eigenspec is an **ANALYSIS SKILL — you (Claude) perform the analysis with judgment.** It is NOT a script that emits a decomposition. Keyword-clustering helpers score a fraction of what an expert spec contains and miss contradictions entirely; do not rely on one. Skills that are analysis/judgment = you do them; only deterministic *validations* (schema checks, lint gates) belong in scripts. ## Step 0 — SET THE REFERENT (do this first, always) Write down (a) the **OBJECTIVE** as a concrete capability, and (b) the **REFERENT** — what an expert spec of this would contain (the bar to beat). You will score your decomposition against this referent at the end. "I produced a spec" is not the target; "my spec ≥ the expert referent" is. ## Step 1 — perform the decomposition (the analysis) Read the prompt plus any relevant prior art in the project (don't re-derive what already exists). Then produce, with judgment: - **Requirement axes (eigenvectors)** — the real, independent dimensions of the requirement (e.g. "AuthN: bearer on all routes", "Health: unauthenticated un-rate-limited probe"), NOT keyword buckets. - **Layered, dependency-ordered task DAG** — each unit with its deps + acceptance criteria. (eigenspec is an analysis you perform with judgment — there is no script that produces the decomposition for you. Any keyword-clustering helper is a shallow hint at best; it does NOT detect contradictions, so never treat it as the analysis.) ## Step 2 — reason about CONTRADICTIONS (this is the part only you can do) Look across the eigenvector pairs and ask: **which requirements conflict?** This is the highest-value step and the one prompt-by-prompt skips. Examples of the pattern to hunt for: - a global concern vs an exemption ("rate-limit everything" ⟂ "/health must always answer") - erase vs retain ("GDPR delete user" ⟂ "audit must keep order→customer") - share vs isolate ("cache all responses" ⟂ "per-user private data") For each conflict, state it explicitly and propose the resolution. ## Step 3 — clarify Ask the user about: every ambiguous or unrecognized term you flagged during decomposition, plus each contradiction whose resolution needs a human decision. Do NOT silently guess flagged items. ## Step 4 — finalize SPEC.md Write a SPEC with: title, the eigenvectors as requirement sections, the task DAG as the build order, a **Contradictions (resolved)** section, and a **Clarifications** section capturing the user's answers. Resolutions are baked in so they're never shipped wrong. ## Step 4.5 — route to capabilities you already have (don't re-invent) When decomposing, check whether a unit can be served by an existing capability instead of being built from scratch. Stay infra-agnostic — route to whatever execution/model/coordination layer the current machine provides (configure it via environment, never hard-code a host, path, or service): - **Execution:** if you have a job runner or background-agent lane, route long/parallel/autonomous units there rather than blocking the interactive session. - **Model dispatch:** reach additional backends through standard environment configuration. Route agentic (tool-using) units to strong-tool backends; generation/judge units anywhere. - **Coordination:** prefer ONE typed bidirectional protocol (e.g. MCP) over ad-hoc HTTP or log-scraping. Hard rules for any coordination unit: loopback/stdio only, no new public ports, explicit lifecycle, search your own prior art first, add ONE concept (not five), pure functions with effects at edges. ## Step 4.6 — design preload (for any unit touching visual design / UI / branding) When a unit involves visual design, decompose the brief on 4 axes (Intent · Audience · Emotion · Constraints); specify color in **hex** not adjectives; specify composition with directional language (thirds / leading lines / negative space); specify lighting with cinematography vocab (key/fill/rim, angle, temperature); append quality tokens. ## Step 5 — hand off Offer to drive implementation directly, or via a spec-driven workflow (specify → plan → tasks → implement). Build in task-DAG order. ## Notes - The method is *domain-general* — it works on software, operations, care work, anything with decomposable requirements. - **Read rough prompts charitably:** silently normalize obvious typos (`rate limt`→`rate limit`, `bearer tokn`→`bearer token`) from context before decomposing; don't let spelling noise distort the eigenvectors. - If the prompt is already crisp, the contradiction scan may find nothing — say so; don't invent conflicts. - The point is the discipline: decompose → find contradictions → resolve in the spec → then build.