Oliver Hughes

Turn a rough request into a task spec a coding agent can run

Convert a one-line feature request into an agent-ready spec with testable acceptance criteria, file boundaries, verification commands and stop conditions.

At a glance

Best for: Developers and PMs delegating features to Claude Code, Codex or background agents who want fewer wrong turns and follow-up questions.
Tested on: Claude · Opus 5.5
You fill in: requestcontext
You get: No blocking questions. I've made the defaults explicit below; change any you disagree with before handing this over. Goal Users can switch the app… (full result below)

Prompt

Turn my rough request into a task spec a coding agent can carry out without coming back to me.

Rough request: {{request}}
Repo context: {{context}}

First, ask me up to 3 questions, but only if the answer would change what gets built. Where a reasonable default exists, pick it and list it under Assumptions instead of asking.

Then write the spec, addressed to the agent in the second person:

• Goal: one sentence describing the user-visible outcome.

• Assumptions

• Acceptance criteria: numbered, each one checkable by a command or a click path.

• Files likely involved (paths), and files that must not change.

• Constraints: allowed dependencies, performance, backwards compatibility.

• Verification: the exact commands to run, whose output the agent must paste into its final report.

• Stop conditions: when to stop and report instead of pushing on.

Keep the spec under 350 words.

Fill in

{{request}}: Your rough, one-line requeste.g. Add dark mode to the dashboard, it should remember the user's choice
{{context}}: Stack, where things live, and how tests rune.g. Vite + React 19 + Tailwind v4; preferences saved via PATCH /api/me/preferences

Example input

request: add dark mode to the dashboard, it should remember the user's choice
context: Vite + React 19 + Tailwind CSS v4, no state library. User settings are saved through PATCH /api/me/preferences (stored in a JSON column). Dashboard pages live in src/pages/dashboard; shared layout in src/components/AppShell.tsx; global CSS in src/index.css. Tests: Vitest + Testing Library (`pnpm test`), Playwright smoke tests in e2e/ (`pnpm e2e`).

1.6k0

Generated Outputs (1)

2 hours ago

Claude

Opus 5.5

2 hours ago

Generated Output

No blocking questions. I've made the defaults explicit below; change any you disagree with before handing this over.

Goal
Users can switch the app between light, dark and system themes, and their choice persists across reloads and devices.

Assumptions

• The theme applies to the whole app, not just the dashboard, since the dashboard shares AppShell.

• There are three options: Light, Dark and System (default).

• The toggle lives in the AppShell header.

Acceptance criteria

1. Choosing Dark adds the dark class to , and the dashboard renders with dark styles.

1. System follows the OS setting and updates live when the OS setting changes.

1. The choice is saved with PATCH /api/me/preferences { "theme": "light" | "dark" | "system" } and restored after login on another browser.

1. The choice is also stored in localStorage and applied by an inline script in index.html before React mounts, so there's no light flash on reload.

1. Text and interactive elements meet WCAG AA contrast in dark mode on the dashboard pages.

1. The toggle is keyboard-operable and has an accessible label.

Files

• Likely: src/index.css, index.html, src/components/AppShell.tsx, a new src/theme/ module, and dashboard components that hard-code colors.

• Must not change: the API server code, or the preferences schema beyond adding the theme key.

Constraints

• No new dependencies.

• Use Tailwind v4's class-based dark variant, declared in src/index.css.

• Replace hard-coded hex colors in the dashboard with theme-aware classes. Don't restyle anything else.

Verification
Run these and paste their output into your final report:
`bash
pnpm test
pnpm e2e
pnpm build
`
Add a unit test for the theme module (it reads the stored value, falls back to system, and applies the class) and one Playwright test: switch to Dark, reload, and assert that html.dark is present.

Stop conditions
Stop and report instead of continuing if:

• the preferences endpoint rejects the new key;

• more than 15 components need color changes (list them instead);

• any existing test fails for a reason unrelated to theming.

Why it works

"Default and list under Assumptions instead of asking" keeps the model from firing ten questions at you while still exposing every choice it made. Acceptance criteria checkable by a command or a click path give the agent a finish line. The must-not-change files and no new dependencies rules cut down the most common kinds of agent sprawl. Stop conditions are the part people forget: they tell the agent when to hand back to you instead of pushing ahead on a wrong assumption. The no-flash criterion encodes something agents usually miss on theme work.

When not to use it

If you don't know yet what you want (an exploration or a design question), a spec gives false precision. Prototype or discuss first. The spec is only as good as the repo context you give it, and a missing detail becomes a confident assumption. For tiny tasks, one clear sentence to the agent is enough.

Comments (0)

No comments yet. Be the first to share your thoughts!