eigenspec

eigenspec — idea → structured PRD

eigenspec is an ANALYSIS SKILL — you (Claude) perform the analysis with judgment. It is NOT a script that emits a decomposition. (Tom, 2026-06-19: "It's supposed to be a skill… a way to analyze the problem, get the eigenvectors, and build the system around it — not a python script.") The deprecated eigenspec.py keyword-clusterer scored ~25% of an expert referent and missed contradictions entirely; do not rely on it. Skills that are analysis/judgment = you do them; only deterministic validations (op-check, clarity-gate, PHI-egress) are scripts.

Step 0 — SET THE REFERENT (do this first, always)

Per [[referent-based-objectives]]: 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 + the relevant harbor prior-art (don't re-derive). 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 bead 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

Use AskUserQuestion for: every clarify_oov term the app flagged, 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 bead 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 5 — hand off

Offer to drive implementation directly, or via spec-kit (specify → plan → tasks → implement). Build in bead-DAG order.

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 THIS 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. Configure the endpoint via env (e.g. ${RUNNER_URL}).
• Model dispatch: reach additional backends through the standard env (ANTHROPIC_BASE_URL / ANTHROPIC_CUSTOM_MODEL_OPTION) — your own local/sovereign models or Claude. Route agentic (tool-using) units to strong-tool backends; generation/judge units anywhere.
• Coordination: prefer ONE typed bidirectional protocol (MCP / LSP-as-comms) 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 / image gen)

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. If you have a local image-generation backend, drive it through the standard OpenAI-compatible /v1/images/generations route configured via env (${IMAGE_API_URL}) — never a hard-coded host.

Notes

• The application is domain-general (works on software, care, anything — it clusters BGE embeddings of the prompt's own terms; no fixed codebook).
• 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.