task-refinement

What this skill does

# Task Refinement

## 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.

**Announce at start:** "I'm using gambit:task-refinement to review and strengthen these tasks."

## Rigidity Level

LOW FREEDOM — Apply all 8 categories to every task. No skipping. Update tasks with fixes, then verify no placeholders remain. Reject plans with critical gaps.

## 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](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](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

```markdown
## 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]
```

---

## Critical Rules

### Rules That Have No Exceptions

1. **Apply all 8 categories to every task** — no skipping any category
2. **Reject plans with placeholder text** — "[detailed above]" = instant reject
3. **Verify after every update** — read back with TaskGet, check for placeholders
4. **Strengthen vague criteria** — "works correctly" must become measurable commands
5. **Add edge cases to every task** — empty, unicode, concurrency, failure modes
6. **Reject tautological tests** — tests must catch specific bugs

### Common Excuses

All mean: **STOP. Apply the full checklist.**

| Excuse | Reality |
|--------|---------|
| "Task looks straightforward" | Edge cases hide in "straightforward" tasks |
| "Has 3 criteria, meets minimum" | Criteria must be MEASURABLE, not just 3+ items |
| "Placeholder is just formatting" | Placeholder = incomplete specification |
| "Can handle edge cases during implementation" | Must specify upfront to prevent rework |
| "Junior will figure it out" | Junior should NOT need to figure anything out |
| "Tests are specified, don't need review" | Test quality matters more than quantity |

---

## Verification Checklist

**Per task reviewed:**
- [ ] Applied all 8 categories
- [ ] Updated task with missing information
- [ ] Verified update (no placeholders remain)
- [ ] Success criteria are measurable
- [ ] Edge cases addressed
- [ ] Test specifications are meaningful

**Overall plan:**
- [ ] Reviewed ALL tasks (no exceptions)
- [ ] Presented structured results
- [ ] Provided clear recommendation

**Can't check all boxes?** Return to the review process.

---

## Examples

See [REFERENCE.md](REFERENCE.md) for detailed examples including:
- Skipping edge case an