--- name: quick-task description: Create a focused task for a bug fix, refactor, or small improvement summary: "Takes a one-off request (bug fix, refactor, performance tweak) and creates a single well-scoped task with acceptance criteria and a test plan — for work outside the main implementation plan." phase: "build" order: 1550 dependencies: [implementation-playbook] outputs: [] conditional: null stateless: true category: pipeline knowledge-base: [task-claiming-strategy] reads: [create-prd, user-stories, coding-standards, tdd, project-structure] argument-hint: "" --- ## Purpose Create a focused, implementation-ready task for a small, well-defined piece of work — a bug fix, refactor, performance improvement, accessibility fix, or minor refinement. Produces a single task with clear acceptance criteria and a TDD test plan, without the full discovery process of the Enhancement prompt. ## Inputs - $ARGUMENTS (required) — description of the task to create - CLAUDE.md (required) — project conventions, key commands, workflow - docs/plan.md (optional) — PRD for requirement context - docs/user-stories.md (optional) — existing stories and epics - docs/coding-standards.md (required) — code conventions, naming, patterns - docs/tdd-standards.md (required) — test categories, mocking strategy, test file locations - docs/project-structure.md (required) — where files live, module organization - docs/implementation-playbook.md (optional) — quality gates section for project-specific gates - docs/system-architecture.md (optional) — for bug fixes involving component boundaries or layer violations - docs/domain-models/ (optional) — for bug fixes involving domain logic or entity relationships - tasks/lessons.md (optional) — previous lessons learned - .beads/ (conditional) — Beads task tracking if configured - Relevant source code — files that will be modified ## Expected Outputs - One well-defined task with acceptance criteria, test plan, and implementation notes - Task created via Beads (`bd create`) if configured, or documented inline - Task summary presented for review ## Quality Criteria - (mvp) Complexity gate applied — redirects to Enhancement if scope is too large - (mvp) Acceptance criteria are testable Given/When/Then scenarios - (mvp) Every criterion maps to at least one test case - (mvp) File paths match project-structure.md conventions - (mvp) Task uses conventional commit title format: type(scope): description - (deep) Duplicate check performed against existing tasks - (deep) lessons.md consulted for relevant anti-patterns - (deep) Implementation notes reference specific coding standards, not generic advice - (deep) Edge cases and regression guards included in acceptance criteria ## Methodology Scaling - **deep**: Full complexity gate, duplicate check, lessons.md review, detailed acceptance criteria with edge cases and regression guards, comprehensive test plan with mocking strategy, specific implementation notes referencing coding standards. - **mvp**: Complexity gate, basic acceptance criteria (happy path + one edge case), test plan with category and cases, file list. Skip duplicate check and detailed implementation notes. - **custom:depth(1-5)**: - Depth 1: complexity gate, basic acceptance criteria (happy path only), and file list. - Depth 2: add one edge case to AC, test cases mapped to criteria, and test file locations. - Depth 3: add duplicate check, lessons.md review, regression guards. - Depth 4: add mocking strategy, specific coding standard references. - Depth 5: full analysis with innovation suggestions and cross-module impact. ## Mode Detection This is a task-creation execution command. Task persistence depends on context: - If Beads is configured, the task is persistent via `bd create`. - If not, the task is documented inline for immediate execution (not persistent). - Always operates in CREATE MODE — produces a task definition each time. ## Update Mode Specifics Not applicable — this creates a new task each time. If a similar task already exists, the duplicate check will surface it for the user to decide. ## Instructions ### The Request $ARGUMENTS --- ### Phase 0: Complexity Gate Before proceeding, evaluate whether this task is actually small enough for Quick Task. If **any** of these are true, **stop and redirect**: 1. The change requires updating `docs/plan.md` or `docs/user-stories.md` 2. The change introduces a new user-facing feature (not a fix or improvement to an existing one) 3. The change affects 3+ unrelated modules or features 4. The change requires new data model entities or schema migrations 5. The change requires competitive analysis or UX research 6. You estimate 4+ Beads tasks will be needed **If any criteria match**, tell the user: > This looks like an enhancement, not a quick task. Redirecting to the Enhancement prompt which handles PRD updates, user stories, and multi-task planning. > > Run: `/scaffold:new-enhancement ` **Hard stop** — do not continue with the Quick Task flow. --- ### Phase 1: Understand & Contextualize #### Review Project Context Before asking questions, review: - `CLAUDE.md` — Project conventions, Key Commands, workflow - `docs/coding-standards.md` — Code conventions, naming, patterns - `docs/tdd-standards.md` — Test categories, mocking strategy, test file locations - `docs/project-structure.md` — Where files live, module organization - `tasks/lessons.md` (if it exists) — Previous lessons learned (extract any relevant to this task) - If `docs/implementation-playbook.md` exists, check its quality gates section for project-specific gates - Relevant source code — Read the files that will be modified #### Check for Duplicates **If Beads:** Run `bd list` and check for existing tasks that overlap with this request. If a matching or overlapping task exists: - Tell the user which task(s) already cover this work - Ask whether to proceed (create a new task) or use the existing one - If proceeding, note the relationship in the new task's description #### Extract Relevant Lessons Review `tasks/lessons.md` (if it exists) for anti-patterns, gotchas, or conventions related to: - The area of code being modified - The type of change (fix, refactor, perf, etc.) - Similar past mistakes to avoid #### Clarify Ambiguities If anything is unclear about the request, use AskUserQuestionTool to batch all questions in a single call. Common clarifications: - What is the expected behavior vs. current behavior? (for bugs) - What metric or outcome defines success? (for performance) - What should NOT change? (for refactors) --- ### Phase 2: Define the Task #### Categorize Determine the task type using conventional commit prefixes: - `fix` — Bug fix (something is broken) - `feat` — Small feature addition within an existing feature area - `perf` — Performance improvement - `a11y` — Accessibility fix - `refactor` — Code restructuring with no behavior change - `chore` — Tooling, dependencies, config - `test` — Adding or fixing tests only - `style` — Code style, formatting (no logic change) #### Priority Assign priority using Beads conventions: - **P0** — Blocking release or breaking production - **P1** — Must-have for current milestone - **P2** — Should-have (default for most quick tasks) - **P3** — Nice-to-have, backlog - **P4** — Backlog / future-consideration (lowest priority; effectively deferred) #### Acceptance Criteria Write 2-5 testable acceptance criteria in Given/When/Then format: ``` Given When Then ``` Each criterion must be unambiguous — pass/fail should be obvious. Cover: - The primary fix or change (happy path) - At least one edge case or error state - Any regression guard (behavior that must NOT change) #### Files to Modify List exact file paths from `docs/project-structure.md`: ``` Files: - src/features/auth/services/session.ts (modify) - src/features/auth/services/__tests__/session.test.ts (modify) ``` #### Test Plan Reference `docs/tdd-standards.md` for the project's test conventions: - **Test category**: unit / integration / e2e (per tdd-standards.md rules for this code area) - **Test cases**: Map each acceptance criterion to at least one test case - **Mocking**: What to mock and what NOT to mock (per the project's mocking strategy) - **Test file location**: Per the project's test file convention #### Implementation Notes - Patterns to follow (reference specific conventions from coding-standards.md) - Known gotchas or pitfalls (from lessons.md or code review) - What is explicitly out of scope --- ### Phase 3: Create the Task **If Beads:** ```bash bd create "type(scope): description" -p # Example: bd create "fix(auth): prevent duplicate session creation on rapid re-login" -p 2 ``` If this task was discovered while doing other work, link the lineage with `discovered-from`: ```bash bd create "fix(parser): handle empty input edge case" \ --type bug -p 2 \ --deps discovered-from:$CURRENT_TASK_ID ``` The new task appears in `bd ready` normally; `discovered-from` is metadata for traceability and does NOT block readiness. **Without Beads:** Document the task inline and proceed directly to implementation. Then set the task description with the full context from Phase 2. Include all of: ``` ## Acceptance Criteria - Given , when , then - ... ## Files to Modify - path/to/file.ts (modify — reason) - path/to/test.ts (modify — add test cases) ## Test Plan **Category**: unit **Cases**: 1. Test description -> validates AC #1 2. Test description -> validates AC #2 **Mocking**: Mock X, do not mock Y **Location**: path/to/__tests__/file.test.ts ## Implementation Notes - Follow pattern from [reference] - Watch out for [gotcha from lessons.md] - Out of scope: [what NOT to do] ``` --- ### Phase 4: Output Summary Present the task summary: ``` +---------------------------------------------------+ | Quick Task Created | +----------+----------------------------------------+ | ID | | | Title | type(scope): description | | Priority | P | | Status | open | +----------+----------------------------------------+ | Acceptance Criteria | | - Given... When... Then... | | - Given... When... Then... | +---------------------------------------------------+ | Files | | - path/to/file.ts | | - path/to/test.ts | +---------------------------------------------------+ | Test Plan | | - Category: unit | | - Cases: N test cases | +---------------------------------------------------+ | Implementation Notes | | - Key note 1 | | - Key note 2 | +---------------------------------------------------+ ``` --- ### Process Rules 1. **Respect the complexity gate** — If it is bigger than a quick task, redirect immediately. Do not try to squeeze a feature into the quick task format. 2. **One task only** — Quick Task creates exactly one Beads task. If you need multiple, use the Enhancement prompt. 3. **Check for duplicates first** — Run `bd list` before creating. Do not create tasks that already exist. 4. **Lessons.md is required reading** — Always check `tasks/lessons.md` (if it exists) for relevant anti-patterns before defining the task. 5. **Acceptance criteria drive tests** — Every criterion must map to at least one test case. If you cannot test it, rewrite the criterion. 6. **Conventional commit titles** — Always use `type(scope): description` format. This feeds directly into commit messages. --- ### When to Use This Prompt - Bug fixes — something is broken and needs fixing - Refactoring — restructuring code without changing behavior - Performance improvements — targeted optimizations - Accessibility fixes — a11y improvements to existing features - Test gaps — adding missing test coverage - Chores — dependency updates, config changes, tooling fixes - Small refinements — polish within an existing feature ### When NOT to Use This Prompt - **New features**: Use `/scaffold:new-enhancement` — new features need PRD updates and user stories - **Multi-task work**: Use `/scaffold:new-enhancement` — if you need 4+ tasks, it is an enhancement - **Initial project setup**: Use the pipeline from `/scaffold:create-prd` forward - **Major refactors**: If the refactor touches 3+ unrelated modules, use `/scaffold:new-enhancement` for proper impact analysis --- ### Quality Standards #### From `docs/tdd-standards.md`: - Every acceptance criterion maps to at least one test case - Test category (unit/integration/e2e) follows the project's rules for this code area - Mocking strategy matches the project's conventions — do not over-mock or under-mock #### From `docs/coding-standards.md`: - File paths match `docs/project-structure.md` conventions - Naming follows project patterns - Implementation notes reference specific standards, not generic advice #### Quality Gates - Quick tasks follow the same quality gates as all other tasks — see `docs/implementation-playbook.md` § Quality Gates #### Eval Gate - If `tests/evals/` exists, run `make eval` (or equivalent eval command from CLAUDE.md Key Commands) as a required pre-commit check --- ### Example Here is what the output looks like for a typical quick task: **Request**: "The save button shows a success toast even when the API returns a 409 conflict" ``` +---------------------------------------------------+ | Quick Task Created | +----------+----------------------------------------+ | ID | abc-123 | | Title | fix(editor): show error toast on | | | 409 conflict during save | | Priority | P1 | | Status | open | +----------+----------------------------------------+ | Acceptance Criteria | | 1. Given the user saves a document, | | when the API returns 409 Conflict, | | then an error toast "Save conflict -- | | someone else edited this document" | | is shown instead of the success toast | | 2. Given the user saves a document, | | when the API returns 200 OK, | | then the success toast still appears | | (regression guard) | | 3. Given the user sees a 409 error toast, | | when they click "Refresh", | | then the latest version is fetched | +---------------------------------------------------+ | Files | | - src/features/editor/services/save.ts | | - src/features/editor/services/__tests__/ | | save.test.ts | +---------------------------------------------------+ | Test Plan | | - Category: unit | | - Cases: 3 (one per AC) | | - Mock: HTTP client. Don't mock toast service. | +---------------------------------------------------+ | Implementation Notes | | - save.ts catches errors but doesn't check | | status codes -- add 409 handling in catch | | - Follow error handling pattern from | | src/features/auth/services/login.ts | | - Out of scope: auto-merge or diff view | +---------------------------------------------------+ ``` --- ## After This Step When this step is complete, tell the user: --- **Quick task created** — Task ready with acceptance criteria, test plan, and implementation notes. **After implementation:** - If this fix revealed a pattern or gotcha: update `tasks/lessons.md`. - If this fix changed a convention or pattern: consider updating `docs/implementation-playbook.md` and `docs/coding-standards.md`. - After merging, consider running `/scaffold:version-bump` if the change is user-facing. **Next:** Run `/scaffold:single-agent-start` or `/scaffold:single-agent-resume` to begin implementation (or `/scaffold:multi-agent-start ` / `/scaffold:multi-agent-resume ` for worktree agents). **Pipeline reference:** `/scaffold:prompt-pipeline` ---