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.

Review complete worker briefs systematically. Find gaps, fix them, present each revised brief in full, and reread it from the root transcript. A brief is ready when a junior engineer can execute it without asking questions.

Core principle: Don't just identify problems — revise each worker brief, present it in full, then reread it with SessionContextRead to verify.

Iron Law: NO worker brief passes review with vague criteria, missing file paths, or placeholder text. Every brief 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 |

| 1. Granularity | Scoped to one sitting (~15-45m)? | Any worker brief 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

• After gambit:brainstorming presents complete first-wave worker briefs

• When reviewing any plan for quality before execution

Don't use for:

• Task already being implemented (too late)

• A worker brief whose wave is already in progress (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.

1. Load the Contract, Wave Plan, and Worker Briefs

Use SessionPlanRead to inspect only the root session's concise wave steps and statuses. Then use SessionContextRead to reread the complete approved epic contract and every full worker brief from the root transcript or latest checkpoint. Do not infer individual worker records from the plan.

2. Review Each Task (All 8 Categories)

2. Review Each Worker Brief (All 8 Categories)

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

For each worker brief, apply every category. No skipping — "straightforward" briefs 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?

• Each worker brief completable in one focused sitting (~15-45 min)?
• Large briefs split into focused briefs with clear deliverables?
• Each resulting brief independently completable?

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

If too large: Split it into complete focused worker briefs in the root transcript. Use SessionPlanWrite only to replace the complete plan when the concise wave summary or ordering changes; represent prerequisites through later waves, never dependency edges.

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?

• Each worker brief 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 4: Wave Order

• Prerequisite work appears in an earlier wave?
• Every parallel wave is represented by one plan step?
• At most one wave is in progress?

Verify the concise wave list with SessionPlanRead; verify the complete worker briefs with SessionContextRead.

Category 5: Anti-patterns

• Task specifies what NOT to do?

• Worker brief 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:

Ask for each worker brief:

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

Add findings to the complete worker brief's Key Considerations section, then present the revised brief in full. 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:

3. Present Each Revised Worker Brief

After reviewing, present each revised full worker brief in the root transcript. Never pass the full brief to SessionPlanWrite:

<!-- gambit-backend:claude -->
TaskUpdate
  taskId: "[task-id]"
  description: |
<!-- /gambit-backend -->
<!-- gambit-backend:codex -->
Present as "Revised Worker Brief: [worker subject]":
<!-- /gambit-backend -->
    [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]
<!-- gambit-backend:claude -->
    - NEW: [Specific anti-pattern for this task's risks]
<!-- /gambit-backend -->
<!-- gambit-backend:codex -->
    - NEW: [Specific anti-pattern for this worker brief's risks]
<!-- /gambit-backend -->

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]"

After revising a brief, present the revised full worker brief in the root transcript. Use SessionPlanWrite only when its concise wave summary, order, or status changes; every such call replaces the complete ordered plan. Then use SessionContextRead to verify the full brief:

SessionContextRead
  read: "revised worker brief from this root transcript"

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]

<!-- gambit-backend:claude -->
### Task-by-Task
<!-- /gambit-backend -->
<!-- gambit-backend:codex -->
### Worker Brief by Worker Brief
<!-- /gambit-backend -->

<!-- gambit-backend:claude -->
#### [Task Name] ([task-id])
<!-- /gambit-backend -->
<!-- gambit-backend:codex -->
#### [Worker Brief]
<!-- /gambit-backend -->
**Status**: [Ready / Needs Revision / Rejected]
**Issues Found**: [count]
**Improvements Made**:
- [What was fixed]
**Edge Cases Added**:
- [What failure modes now addressed]

<!-- gambit-backend:claude -->
[Repeat for each task]
<!-- /gambit-backend -->
<!-- gambit-backend:codex -->
[Repeat for each worker brief]
<!-- /gambit-backend -->

### Summary
<!-- gambit-backend:claude -->
- Tasks updated: [list]
<!-- /gambit-backend -->
<!-- gambit-backend:codex -->
- Worker briefs revised and presented in full: [list]
- Concise wave summary/order/status changes: [list or none]
<!-- /gambit-backend -->