Menu
Use when operator starts a new ticket ("ship X", "build Y", "add feature", "fix workflow") and no spec exists; produces spec, clarify questions, acceptance criteria. Do NOT use for code edits, mid-flight reorgs, or after a spec is locked.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use ONLY when the operator runs "/find-wasted-code" (or explicitly asks to "scan the repo for dead-end tool calls / broken links / missing helpers / footgun configs / silent push-through"). Statically scans THIS repo for friction footguns and writes a tracked report to docs/wasted-code/report.md. Manual-trigger ONLY — do NOT auto-invoke; the skill carries disable-model-invocation and no hook wires it. Read-only except the one report write. Findings are review candidates, never auto-fixes. Do NOT use for token/transcript economy (/token-waste-audit), for process ceremony (/find-wasted-effort), or for CLI/Flow drift health (/fusebase-health).
Use at Specify to classify a ticket Full vs Lightweight, and whenever a change looks small / reversible / low-risk ("small fix", "tweak", "hotfix", "drop pretty-printing", "bump a constant"). Operationalizes FR-21 — ceremony proportional to change size. Defines the eligibility gate, the change-note artifact, the one-pass build→verify→deploy procedure, and mid-flight promotion. Do NOT use for risky/uncertain work, schema/data migrations, security/permission changes, new public contracts needing a decision, unknown-root-cause diagnostics, or large features — those take the Full lane.
ALWAYS load at session start. After self-attesting, Read references/<role>.md for your role (Product Owner / AI Developer / Architect / Deploy phase) — role-specific don't-list, exact refusal phrasing for FR violations, and recovery pointers; shared cross-role protocols live in this file. Mandatory; not on-demand.
Use when the operator types /product-owner, asks to activate Product Owner, start a Product Owner or PO session, or searches /product in Codex for Fusebase Flow project management. Do NOT use for implementing code; route implementation to the AI Developer role.
Use when planning tasks that touch big source files, when an edit would push a file past the module-size ceiling, when the pre-commit module-size ratchet warns or blocks, or when generating policies/module-size-baseline.txt. Operationalizes FR-25 — module-size ratchet (ceiling default 800; over-ceiling files may shrink, never grow; extraction along a responsibility seam is in-scope, not scope creep). Do NOT use for docs/markdown size (FR-23 owns docs), to force decomposition of an existing monolith (that is its own explicit ticket), or to judge split quality by regex (seam-vs-mechanical is semantic — code-review owns it).
Use ONLY when verification passed AND operator explicitly says "prepare deploy" / "draft deploy" / "ship it"; drafts deploy handoff, captures deploy hash + probes + smoke, advises spec DRAFT→DONE flip. Do NOT auto-invoke; operator triggers explicitly.
| name | requirements-specification |
| description | Use when operator starts a new ticket ("ship X", "build Y", "add feature", "fix workflow") and no spec exists; produces spec, clarify questions, acceptance criteria. Do NOT use for code edits, mid-flight reorgs, or after a spec is locked. |
| source_inspiration | conceptual-only |
| license_status | clean-room-original |
| fusebase_flow_version | 2.1 |
| risk_level | low |
| invocation | automatic |
| expected_outputs | ["docs/specs/<slug>/spec.md","docs/specs/<slug>/clarify-conversation.md"] |
| related_workflows | ["eight-phase-flow.md","session-initiation.md"] |
| hook_dependencies | ["none"] |
Turn vague operator intent into a versioned spec with explicit acceptance criteria, unresolved clarify questions, and risk notes. The output is the contract every later skill (planning, implementation, validation, code review, security, deploy) reads.
docs/backlog/<slug>/README.md and operator says "promote it"Specify or Clarify (per FLOW_RULES state announcement)docs/specs/<slug>/spec.md already exists and is scope-locked (decisions frozen; decisions.md shows Lock status: LOCKED) or its status is DONE (spec Status is DRAFT-until-DONE; scope-lock is a decisions.md flag, not a Status value)Before drafting a spec, classify the ticket Full or Lightweight using the eligibility gate in flow-skills/lightweight-lane/SKILL.md. If the change is small, reversible, security-neutral, mechanically-verifiable, needs no architectural decision, and the root cause is known → it is Lightweight: do NOT draft spec/clarify/decisions/tasks/gate. Instead produce a single change-note (templates/change-note.md) and route to workflows/lightweight-lane.md (one build→verify→deploy pass, plain operator go-ahead). In doubt → Full (continue below). The skip-clarify gate that follows is a Full-lane micro-optimization (it skips clarify only); the Lightweight lane is the bigger lever for genuinely small work.
Then run the FR-23 documentation-budget classifier (flow-skills/documentation-budget/SKILL.md) before creating any spec artifact: Tier 0 (transient / already captured in code/tests/git) → no doc; Tier 1 (Lightweight) → change-note only; Tier 2 (mid-flight restart) → docs/tmp/handoff.md only; Tier 3/4 → proceed to a full spec below. Do NOT create docs/specs/<slug>/ artifacts for Tier 0/1/2 work. When unsure between tiers, choose the higher.
The clarify phase exists to surface hidden ambiguity before code is written. Skipping it has a cost — undetected ambiguity surfaces later as wrong-direction code or operator-rework. Skip ONLY when ALL of the following hold:
| Skip condition | Concrete check |
|---|---|
| Single file, single function | Affects exactly one file; one named function or contiguous block |
| No new dependency / API / config | No package.json, no env var, no policy file change |
| Acceptance criterion fits in one sentence | "X now returns Y instead of Z" or equivalent |
| Operator typed "skip clarify" verbatim | Not inferred from "this is small" |
| No constitution-invariant question raised | Worker-undisturbed, mixed-fleet, auth gates all unaffected |
If ANY condition is unmet: run clarify, even if the operator pushes for speed. The phrase "the spec for a small fix is two paragraphs" applies (per docs/operator-discipline.md OD-6).
When skipping: spec.md is still drafted and its scope is frozen in the same step (spec Status: DRAFT — scope-lock is recorded in decisions.md (Lock status: LOCKED), NOT as a Status: LOCKED value; the Status stays DRAFT until the deploy session flips it to DONE). The clarify-conversation.md file is replaced by a one-line note: Clarify skipped per operator request; ticket meets skip-clarify gate (see requirements-specification/SKILL.md).
For bug investigation tickets where the root cause is unknown, split the spec into two phases:
Phase 1 — Diagnostic. Acceptance criterion is "we can name the root cause + cite evidence". No production code change. Output: an investigation note in docs/specs/<slug>/diagnostic.md with reproduction steps, suspected component, and evidence (logs, traces, repro). The phase ends when the operator confirms the diagnosis.
Phase 2 — Fix. Drafted as a separate spec section (or separate spec file <slug>-fix/spec.md) AFTER Phase 1 closes. Acceptance criteria are concrete code changes; verification gate references the diagnostic.
Why split: collapsing both phases lets the implementer guess at fixes while the bug is still not understood — produces "shotgun debugging" commits and burns context. The split also makes it explicit when the operator should be asked "is the root cause confirmed?" before you write any code.
When NOT to split: the bug is already understood (e.g., known typo, obvious off-by-one, broken import). Single-phase spec is fine.
| Input | Where it lives | If missing |
|---|---|---|
| Backlog ticket or operator intent | docs/backlog/<slug>/README.md or chat | Ask operator for one-liner + why-now + rough scope |
| Constitution / project context | FLOW_RULES.md + project-specific values in AGENTS.md | Stop and ask operator to fill AGENTS.md project-specific section |
| CLI edition map, for Fusebase Apps work | docs/fusebase-cli-edition.md | Continue with Flow-only spec, but mark CLI domain assumptions unknown |
| Letter prefix in use | Project-specific section of AGENTS.md | Default to A; ask operator to confirm |
docs/fusebase-cli-edition.md and identify any CLI domain skills that should inform scope, constraints, or acceptance criteria. Use them as supporting context; do not copy their content into the spec.docs/specs/<slug>/clarify-conversation.md using templates/clarify-conversation.md.flow-skills/design-discovery-ideation/SKILL.md before drafting the final clarify options. Capture the selected direction in clarify-conversation.md or spec.md.clarify-conversation.md with locked answers.docs/specs/<slug>/spec.md using templates/spec.md. Status: DRAFT.flow-skills/app-quality-patterns/SKILL.md; every pattern whose Trigger matches this feature becomes an AC citing its ID (e.g., "AC4 — filter/report state encoded in URL; refresh restores the exact view (QP-01)"). Cite IDs only — do not paste pattern bodies (FR-23). For audience-classified surfaces (docs/audience.md exists — or the operator explicitly requested a client-vs-internal posture check — and client-vs-internal classified the surface): each applicable posture checklist row becomes an AC citing its C/I/S ID (e.g., "AC7 — destructive actions confirm before executing (client-vs-internal C2)"); where a row overlaps a QP pattern, cite both IDs on one AC line.Specify to Plan once spec.md is saved.| Artifact | Path | Mode |
|---|---|---|
| Spec | docs/specs/<slug>/spec.md | Mode B (full) |
| Clarify conversation | docs/specs/<slug>/clarify-conversation.md | Mode B (full) |
| Backlog index update (if promoted) | docs/backlog/index.md | Mode B (full) |
| Failure mode | Detection | Response |
|---|---|---|
| Operator can't answer clarify question | After 1 round, operator says "I don't know" | Park spec at BLOCKED status; file follow-up backlog ticket for the unknown |
| Backlog ticket conflicts with FLOW_RULES invariant | Constitution check fails | Stop. Ask operator to revise scope OR amend project-specific rules. Don't proceed silently. |
| Scope is actually two tickets | Spec needs >12 acceptance criteria, multiple deploys, or splits naturally | Stop. Propose splitting into <slug>-a and <slug>-b backlog tickets. |
| Investigation reveals the ticket is wrong | During clarify, evidence shows the reported behavior is intentional, the bug is elsewhere, or the feature already exists | Abort the ticket. Mark spec status ABORTED with one paragraph: what was investigated, what was found, why no work follows. Move ticket back to docs/backlog/<slug>/README.md with status aborted-on-investigation so it doesn't reappear. Do NOT silently downscope to "fix the wrong thing instead." |
| Operator and clarify keep disagreeing on scope | After 2 rounds of clarify, the gap between operator's intent and what the spec captures is widening | Stop. Switch to a 1:1 clarify-only chat: ask the operator to restate the goal in 3 sentences. If the gap persists, escalate to architect (workflows/architect-escalation.md) — the framing problem is bigger than spec drafting can resolve. |
workflows/architect-escalation.mddesign-discovery-ideation before locking the spec directionimplementation-planning skill in "decision-only" mode to surface trade-offsdecisions.md here — that's implementation-planning's jobtasks.md here — sameOriginal Fusebase Flow content. Designed after reviewing public AI coding workflow patterns; no third-party code, prompts, skill files, or hook scripts are copied. See docs/source-map.md.