task-refinement

name	task-refinement
description	Refines prepared work briefs until each one is executable by a junior engineer without questions.
when_to_use	Use this implementation mechanic to refine prepared work briefs only when explicitly invoked by name or called by an active Gambit workflow owner; do not select it implicitly as a peer workflow.
user_invokable	true

Task Refinement

Freedom: LOW — apply all 8 categories to every brief; reject anything with placeholders or critical gaps.

Overview

Review Tasks systematically. Find gaps, fix them, verify fixes. A task is ready when a junior engineer can execute it without asking questions.

Core principle: Don't just identify problems — fix them. Update each Task, then read it back to verify.

Iron Law: NO task passes review with vague criteria, missing file paths, or placeholder text. Every task must be executable by a junior engineer without questions. No exceptions.

Quick Reference

Category	Key Check	Auto-Reject If
1. Granularity	Scoped to one sitting (~15-45m)?	Any task without breakdown estimate
2. Implementability	Junior executes without questions?	Vague language, missing file paths
3. Success Criteria	Measurable, verifiable?	"Works correctly", "is implemented"
4. Dependencies	Correct blocking order?	Circular or missing dependencies
5. Anti-patterns	Forbidden patterns specified?	No anti-patterns section
6. Edge Cases	Empty/unicode/concurrent/failure?	No edge case consideration
7. Red Flags	Placeholder text? TODOs?	"[detailed above]", "[as specified]"
8. Test Quality	Tests catch real bugs?	Tautological or happy-path-only tests

When to Use

• Before gambit:executing-plans starts implementation
• After gambit:brainstorming creates tasks
• When reviewing any plan for quality before execution

Don't use for:

• Task already being implemented (too late)
• Creating plans from scratch → gambit:brainstorming
• Debugging → gambit:debugging

The Process

1. Load All Tasks

TaskList

Identify the epic and all subtasks. Read each with TaskGet.

2. Review Each Task (All 8 Categories)

For each task, apply every category. No skipping — "straightforward" tasks hide the worst edge cases.

Category 1: Granularity

• Each task completable in one focused sitting (~15-45 min)?
• Large tasks broken into subtasks with clear deliverables?
• Each subtask independently completable?

If too large: Create subtasks with TaskCreate, link with addBlockedBy.

Category 2: Implementability

• Can a junior engineer execute without asking questions?
• All file paths specified (or marked "TBD: new file")?
• Function signatures/behaviors described, not just "implement X"?
• "Done" clearly defined?

Red flags: "Implement properly", "Add support", "Make it work", missing file paths.

Category 3: Success Criteria

• Each task has 3+ specific, measurable criteria?
• All criteria verifiable with a command or code review?
• No subjective criteria?

Rewrite vague criteria into measurable ones:

• "Authentication works" → "POST /auth/login with valid creds returns 200 + JWT; invalid creds returns 401"
• "Code is good quality" → "Lint clean, no TODOs, no panic/unwrap in production code"
• "Tests pass" → "Run npm test, 0 failures, exit 0"

Category 4: Dependencies

• blockedBy relationships correct?
• No circular dependencies?
• Dependency graph logically ordered?

Verify with TaskList output.

Category 5: Anti-patterns

• Task specifies what NOT to do?
• Includes: no TODOs without issue refs, no stub implementations, no swallowed errors?
• Error handling requirements specified?

Category 6: Edge Cases

Ask for each task:

• What happens with empty/nil/zero input?
• What happens with malformed input?
• What about Unicode, special characters, large inputs?
• What about concurrent access?
• What when dependencies fail?

Add findings to task's Key Considerations section. See REFERENCE.md for edge case examples.

Category 7: Red Flags (AUTO-REJECT)

If any found, REJECT the plan:

• Placeholder text: "[detailed above]", "[as specified]", "[complete steps here]"
• Vague instructions: "implement properly", "add support"
• Unverifiable criteria: "code is good", "works well"
• "We'll handle this later" or "TODO" in the plan itself
• Missing test specifications

Category 8: Test Quality

Tests must catch real bugs, not inflate coverage.

For each test specification, ask:

• What specific bug would this test catch?
• Could production code break while this test passes?
• Does the assertion verify behavior, not just existence?

Reject: Tests that only verify syntax/existence, tautological tests, tests without meaningful assertions, generic test names ("test_basic").

See REFERENCE.md for good/bad test examples.

---

3. Update Each Task

After reviewing, update each task with fixes:

TaskUpdate
  taskId: "[task-id]"
  description: |
    [Original content, preserved and strengthened]

    ## Key Considerations (ADDED BY REVIEW)

    **Edge Case: [Name]**
    - [What could go wrong]
    - MUST [specific mitigation]

    ## Anti-patterns
    [Original anti-patterns]
    - NEW: [Specific anti-pattern for this task's risks]

Rules for updates:

• Preserve original intent
• Strengthen vague criteria into measurable ones
• Replace ALL placeholder text with actual content
• Add edge case analysis

---

4. Verify Updates (MANDATORY)

After every TaskUpdate, read back with TaskGet and verify:

TaskGet
  taskId: "[task-id]"

Check:

• All sections contain actual content (not placeholders)
• Success criteria are measurable
• Edge cases addressed
• File paths specified
• No "[detailed above]", "[as specified]", or similar

If ANY placeholder found: Rewrite with actual content immediately.

---

5. Present Results

## Plan Review Results

### Overall: [APPROVE / NEEDS REVISION / REJECT]

### Task-by-Task

#### [Task Name] ([task-id])
**Status**: [Ready / Needs Revision / Rejected]
**Issues Found**: [count]
**Improvements Made**:
- [What was fixed]
**Edge Cases Added**:
- [What failure modes now addressed]

[Repeat for each task]

### Summary
- Tasks updated: [list]
- Critical issues found: [count]
- Recommendation: [approve/revise/reject with reasoning]

---

Examples

See REFERENCE.md for detailed examples including:

• Skipping edge case analysis vs. full analysis (VIN scanner example)
• Accepting vague criteria vs. rewriting as measurable (encryption example)
• Good vs. bad test specifications

---

6. Chain to Execution

After refinement is complete, route to execution.

Invoke executing-plans directly — it enters the epic worktree automatically:

Skill skill="gambit:executing-plans"

Announce it in one line first ("Tasks refined and ready — starting execution.") so the transition is visible.

---

Integration

Called by:

• gambit:brainstorming (optional, user chooses at handoff)
• User via /gambit:task-refinement

Calls:

• gambit:executing-plans (invoked directly after refinement — enters the epic worktree automatically)

Workflow:

gambit:brainstorming → gambit:task-refinement → gambit:executing-plans
                                ↓
                         (if gaps: revise tasks, re-review)