From greenloop
Reconstruct a design spec (SPEC.md) for a codebase that doesn't have one — derive observed behavior from the code, interview the user to separate intent from accident, and produce a section-numbered, provenance-marked spec that app-audit can generate its checklist from. Use when the user asks to write or create a design spec, document what the app should do, or formalize requirements for an existing app — and automatically when app-audit Phase 1 finds no spec. Every statement is marked [confirmed] / [observed] / [assumed] so audits know how much to trust each claim. Optional formal surface: EARS-form requirements and Gherkin scenarios (which seed the acceptance map), architectural decisions captured as ADRs, and a C4-style context/container diagram generated from cartographer's codemap.
How this skill is triggered — by the user, by Claude, or both
Slash command
/greenloop:spec-bootstrapThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Reconstruct a design spec for a codebase that never had one (or whose spec is long dead).
Reconstruct a design spec for a codebase that never had one (or whose spec is long dead).
The audit system's strongest machinery — checklist generation, spec-compliance category, spec_refs — assumes a design spec exists. Most AI-built apps don't have one. Without a spec, "does the code match the intent?" is unanswerable, and the residual-error problem ("we kept fixing things and errors kept remaining") is partly unspecified intent: nobody ever wrote down what the app must and must never do, so no audit could check it.
A bootstrapped spec is reconstructed intent, not original intent. The code shows what the app does; only the user knows what it should do. The gap between those two is exactly where the bugs live — which is why the interview (Phase 3) is the heart of this skill, not the code reading.
Do NOT use when a current spec exists and just needs updating — that's an ordinary edit, not a bootstrap.
Every normative statement in a bootstrapped spec carries a provenance marker:
| Marker | Meaning | How audits treat violations |
|---|---|---|
[confirmed] | The user explicitly affirmed this is intended behavior | Normal finding at normal severity |
[observed] | The code does this consistently; user hasn't been asked | Normal finding, with a note that the baseline is observed not confirmed |
[assumed] | Inferred from convention or partial evidence; plausible but unverified | Not a finding — a question (app-audit Phase 3.6: ask, don't flag) |
The markers are the honesty layer. A spec where everything silently looks authoritative would launder guesses into requirements — violations of guessed requirements are noise, and noise erodes trust in the audit. The goal of the interview is to move as many statements as possible to [confirmed].
*DESIGN*.md, *SPEC*.md, ARCHITECTURE.md, .codemap/spec-config.yml canonical_spec).Build the factual skeleton from the code. Use cartographer's codemap if present (build it if not — this is a legitimate auto-trigger); fall back to direct exploration otherwise.
Catalog:
This phase is mechanical. No normative claims yet.
For each inventory item, write candidate normative statements in spec language — and mark every one [observed] or [assumed]:
DELETE route that requires a confirmation token → "Destructive actions require explicit confirmation [observed]"[observed]"[observed] — value found in code; intent unknown"Two derivation rules:
Convert [observed]/[assumed] into [confirmed], and capture intent that is not in the code at all. Full question design and batching rules: references/interview-protocol.md. The essentials:
[assumed] forever; "should deleting an account cascade to backups?" cannot.Outcome classes from each answer:
[confirmed][confirmed][assumed], listed in the spec's open-questions sectionUse the structure in references/spec-template.md. Non-negotiables:
## 3. Surfaces, ### 3.2 Calendar) so cartographer's spec_refs and app-audit's checklist machinery work against it.v1 (bootstrapped YYYY-MM-DD) in the header, so spec-drift detection has an anchor.[assumed] plus the user's "I don't know yet" answers.Optional formalization (offer once, don't impose). Prose requirements are
ambiguous in predictable ways ("the app should handle errors" — which errors,
doing what?). Two formal surfaces fix specific ambiguity classes — formats and
worked examples in references/formal-spec.md:
WHEN <trigger> [WHERE <state>] THE SYSTEM SHALL <response> next to the
prose (the prose stays primary; EARS is the precision layer). Apply it where
ambiguity is expensive — data loss, security, money, concurrency — not to
every sentence; a fully-EARS spec is unreadable.Given/When/Then scenario
goes in the spec section it formalizes, carries the section number, and
seeds the acceptance map (app-audit Step 1.3b) — a scenario is a test
specification, so an UNMAPPED row already says exactly what the missing test
must assert. Provenance markers carry over: a scenario derived from an
[assumed] statement is itself assumed, and stays out of the acceptance map
until confirmed.[confirmed] by definition)..codemap/spec-config.yml naming the new spec as canonical_spec.docs/adr/
(NNNN-<slug>.md, Context / Decision / Consequences — template in
references/formal-spec.md §3). The spec states what must hold; the ADR
preserves why it was chosen, which is what the next person needs before
un-choosing it. Cross-link: spec section cites the ADR, ADR cites the
section.docs/architecture.md.
Recipe: references/formal-spec.md §4. Mark it [observed] — it
describes the code as mapped, and regenerates on request rather than
rotting.Don't auto-invoke app-audit; the user decides when to audit.
The interview is the heart of this skill, and there is no user to interview. Headless behavior:
[observed]/[assumed] and the header stamped DRAFT — UNCONFIRMED (no interview).spec-config.yml pointing at it as canonical — an unconfirmed draft must not silently become the source of truth. Instead note it for the user.[observed] violations are findings-with-caveat, [assumed] violations are questions queued for the user.[confirmed], [observed], or [assumed].canonical_spec.| Skill | Relationship |
|---|---|
| cartographer | Provides the inventory (Phase 1) and consumes the result (spec_refs, doc classification after Phase 5) |
| app-audit | Invokes this skill from Phase 1 when no spec exists; generates its checklist from the bootstrapped spec; respects provenance markers when grading spec-compliance findings |
| audit-fix | Indirect — fixes the "known deviations" findings this skill pre-seeds |
references/spec-template.md — the SPEC.md structure: section layout, normative-statement style, provenance markers, versioning, open-questions and known-deviations sections. Read in Phase 4.references/interview-protocol.md — question design, batching, stakes-ordering, and the answer→outcome mapping. Read before Phase 3.references/formal-spec.md — EARS patterns with worked rewrites, Gherkin scenario style + acceptance-map seeding, the ADR template, and the C4-from-codemap Mermaid recipe. Read for Phase 4's formalization offer and Phase 5 step 4.npx claudepluginhub apourmd941/selran-devloop --plugin greenloopProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.