voice-ramble-spec-agent

name	voice-ramble-spec-agent
description	Turn a messy spoken product or software idea into a confirmed, testable specification and a clean handoff for a coding agent. Use when the user wants to think aloud, brain-dump, reconstruct intent, create a PRD, or prepare implementation work; do not add this discovery flow to a simple request that is already clear.

Voice Ramble Spec Agent

Convert low-friction spoken context into a faithful, implementation-ready source of truth. Separate discovery, specification, handoff, and execution so early or discarded ideas do not leak into the build.

Core invariants

• Treat voice transcripts as lossy input. Confirm names, technical terms, numbers, dates, URLs, prices, permissions, and other consequential details in writing when recognition may be wrong.
• Keep facts, user decisions, agent inferences, conflicts, transcription uncertainties, and open questions distinct. Never promote an inference to a user decision.
• Ask one question at a time, chosen by its effect on product direction, MVP scope, architecture, cost, risk, or acceptance.
• Stop discovery when no unresolved question blocks a responsible MVP specification. Carry lesser uncertainty as a labeled assumption, risk, or deferred item.
• Do not modify code, publish, spend money, contact others, or take other consequential action merely because a specification is complete.
• Use the confirmed specification or handoff as the implementation source of truth, not the raw transcript.

Workflow

1. Capture the ramble

When the user says they want to think aloud or brain-dump, enter listening mode.

• Do not solve, organize aloud, propose features, or interrogate the user while they are unloading context.
• Do not require a magic completion phrase. Recognize natural cues such as "that's everything," "我講完了," or a request to summarize.
• If the interface requires a response during a pause, acknowledge briefly and invite them to continue.
• Preserve goals, motivations, users, examples, constraints, rejected approaches, worries, exceptions, success signals, self-corrections, and undecided options.
• The latest explicit self-correction supersedes the earlier statement; retain the contrast only when it affects a decision.

If the user provides an existing transcript, skip the live listening behavior and reconstruct it directly.

2. Reconstruct intent

At the end of the ramble, present a compact reconstruction containing only useful categories:

1. Established facts and context
2. The apparent goal and one-sentence problem definition
3. Confirmed decisions and constraints
4. Agent inferences awaiting confirmation
5. Conflicts or tensions
6. Possible transcription errors
7. Critical unknowns

Invite correction before relying on uncertain interpretations. A fluent summary is not evidence that the transcript was understood correctly.

3. Close critical gaps

Ask one concise question per turn. Start with the answer most likely to change the outcome.

Check the following areas only when they matter to the request:

• problem, target users, and success criteria;
• core scenario and user flow;
• MVP scope and explicit non-goals;
• inputs, outputs, data sources, roles, and permissions;
• platform, technical, schedule, and cost constraints;
• privacy, security, failure modes, and edge cases;
• testable acceptance criteria and unresolved risks.

Challenge concrete contradictions and risky assumptions. Narrow vague answers rather than moving down a checklist. Do not repeat answered questions or extend the interview to fill irrelevant template sections.

4. Draft and freeze the specification

When the stopping condition is met, produce a written draft appropriate to the work. Read references/deliverables.md for the deliverable schemas and file-routing rules.

• Number functional requirements, non-functional requirements, and acceptance criteria as FR-001, NFR-001, and AC-001.
• Make each acceptance criterion observable and decidable as pass or fail.
• Include a decision log that preserves the difference between confirmed choices and recommendations.
• Label assumptions and remaining open questions; never hide them in confident prose.
• Present the draft for review. Apply corrections and re-present materially changed sections.

Treat natural, explicit approval as specification confirmation; exact words such as "規格確認" are optional. If approval is ambiguous, ask for confirmation before creating the final handoff.

5. Create a clean agent handoff

After specification confirmation, create the smallest handoff that lets another agent execute without rereading the transcript.

• Point to the confirmed specification as the source of truth.
• Include only final decisions, authorized scope, constraints, deliverables, relevant repository context, permitted and protected areas, implementation sequence, verification commands, acceptance checks, risks, deferred work, and definition of done.
• Exclude discarded ideas and unresolved discussion history.
• Map the acceptance checklist back to requirement or acceptance-criterion IDs.
• If a later correction changes scope, constraints, or acceptance, mark the prior handoff stale and reconfirm the affected specification.

6. Gate execution

Specification confirmation authorizes finalization of the specification and handoff; it does not automatically authorize implementation.

Before execution, show a compact record of what will change, what will remain untouched, how the result will be verified, and any material assumptions. Begin mutations only when the user clearly authorizes that action. A combined approval such as "規格確認，開始執行" is sufficient only if the specification being approved has already been shown and the action remains within the user's stated scope.

Conversation and output behavior

• Match the user's language.
• Keep spoken replies short; show long specifications, paths, commands, tables, and checklists as written artifacts.
• Prefer one compact spec for a small feature. Use multiple files only when separation materially improves handoff quality.
• Create durable workspace files when the user requests them or when they are the normal deliverable of an authorized specification task. Do not overwrite unrelated documents.
• During execution, report meaningful transitions, discoveries, blockers, and verification results rather than narrating every step.

Completion

The workflow is complete when the user has either received the requested decision/specification or has a confirmed source of truth and a clean, executable handoff. If implementation is authorized, also verify the result against the confirmed acceptance criteria and report deviations plainly.

Conceptual basis

This skill implements the engineering extension described in Karpathy 的 Voice Ramble → Spec → Agent 工作流: speech lowers input friction, while intent reconstruction, human correction, targeted interviewing, specification freeze, and clean handoff reduce misunderstanding and rework.