القائمة
Review generated tasks for completeness, correctness, and coherence before execution
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Ask the Cerberus model panel an arbitrary question
Produce a technical implementation plan (design-focused), optionally interviewing the user, then run multi-model generator and plan review gate
Interview the user to produce a feature spec, then run multi-model generator and spec review gate
Iterative code review with external reviewers
Iterative plan review with external reviewers
Iterative spec review with external reviewers
| name | review-tasks |
| disable-model-invocation | true |
| description | Review generated tasks for completeness, correctness, and coherence before execution |
| argument-hint | [--from-plan <path/to/plan.md>] [--beads] |
Before running any Bash snippet in this skill, run the shared Cerberus resolver below. It lazily builds and executes bin/cerberus from the configured plugin root.
# --- shared resolver (canonical body; identical across all callers) ---
set +u
if [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${PLUGIN_ROOT:-}" ]; then
host=codex
elif [ -n "${CLAUDE_SESSION_ID}" ] || [ -n "${CLAUDE_PLUGIN_ROOT}" ] || [ -n "${CLAUDE_SKILL_DIR}" ]; then
host=claude
else
host="${CERBERUS_HOST:-}"
if [ "$host" = claude-code ]; then
host=claude
fi
fi
root="${CERBERUS_ROOT:-}"
if [ -z "$root" ] && [ "$host" = codex ]; then
root="${PLUGIN_ROOT:-}"
fi
if [ -z "$root" ] && [ "$host" = codex ] && [ -n "${CODEX_THREAD_ID:-}" ]; then
cache_home="${HOME:-}"
[ -n "$cache_home" ] || cache_home="${USERPROFILE:-}"
if [ -n "$cache_home" ]; then
cache_file="$cache_home/.codex/cerberus/sessions/$CODEX_THREAD_ID/plugin-root"
if [ -r "$cache_file" ]; then
IFS= read -r root < "$cache_file" || true
fi
fi
fi
if [ -z "$root" ] && [ "$host" != codex ]; then
root="${CLAUDE_PLUGIN_ROOT}"
[ -n "$root" ] || root="${PLUGIN_ROOT:-}"
fi
if [ -z "$root" ] && [ "$host" != codex ]; then
skill_dir="${CLAUDE_SKILL_DIR}"
if [ -n "$skill_dir" ]; then
root="$(cd "$skill_dir/../.." && pwd)"
fi
fi
[ -n "$root" ] || { echo "cerberus: plugin root not set; set CERBERUS_ROOT and retry" >&2; exit 127; }
bin="$root/bin/cerberus"
export CERBERUS_ROOT="$root"
claude_session="${CLAUDE_SESSION_ID}"
if [ "$host" = claude ]; then
export CERBERUS_HOST=claude
elif [ "$host" = codex ]; then
export CERBERUS_HOST=codex
fi
if [ "$host" = codex ] && [ -n "${CODEX_THREAD_ID:-}" ]; then
export CERBERUS_HOST=codex CERBERUS_SESSION_ID="$CODEX_THREAD_ID"
elif [ "$host" = claude ] && [ -n "$claude_session" ]; then
export CERBERUS_HOST=claude CERBERUS_SESSION_ID="${CERBERUS_SESSION_ID:-$claude_session}"
fi
command -v make >/dev/null 2>&1 || { echo "cerberus: make not found on PATH; install make and retry." >&2; exit 127; }
if ! make -q -C "$root" build >/dev/null 2>&1; then
command -v go >/dev/null 2>&1 || { echo "cerberus: Go >= 1.22 not found on PATH; install Go and retry." >&2; exit 127; }
echo "cerberus: building... (this happens once after clone or upgrade)" >&2
start=$(date +%s)
make -C "$root" build >&2 || exit $?
end=$(date +%s)
echo "cerberus: build complete in $((end-start))s" >&2
fi
# --- shared resolver above; per-caller exec below (allowed to diverge) ---
exec "$bin" "$@"
Use bin/cerberus through the configured plugin root when invoking Cerberus commands below.
Validate that generated tasks form a coherent, complete, and executable work graph. Ensures the set of tasks will actually accomplish the plan's objectives with no gaps, no orphans, and clear completion criteria.
Upstream: This command validates output from
/create-tasks.
⚠️ ITERATION REQUIRED: This command does NOT stop after identifying issues. You MUST attempt safe fixes and re-run validation until verdict is PASS, max iterations are reached, or an unfixable plan-level blocker requires user input. See Iteration Loop section.
Validate the generated task graph against its plan and, when the artifact is editable, apply the smallest safe fixes so the final graph is executable.
Recompute the state needed for the gates: plan coverage, file-to-task mapping, dependency graph, task format/completability, sizing, TDD/wiring checks when applicable, and the No-Stragglers rollup. For Beads mode, run br ready after fixes when tooling is available.
Return the Task Review Summary shape below with a PASS / FAIL / FAIL (MAX_ITERATIONS_REACHED) verdict, blocking issues, warnings, iterations used, and machine-readable JSON. Do not include hidden reasoning or earlier failed drafts.
For task graphs with more than 10 tasks, partition local checks by epic, sub-epic, parent, or phase so each pass stays focused. Global checks must still see summaries of all plan items, tasks, file mappings, dependencies, and parent relationships. The No-Stragglers gate is global and cannot be approximated from a sample.
Completing ALL tasks MUST result in completing the FULL and COMPLETE plan.
This is the single most important property of a valid task graph. If this property fails, the entire review fails. A user who completes every task must have a fully implemented feature—not 90%, not "mostly done", but COMPLETELY DONE.
You MUST NOT pass a review where any plan objective, acceptance criterion, or MUST/SHALL obligation would remain unimplemented after all tasks complete.
This review PASSES when ALL of the following are true:
br ready via dependency completionsVerdict is FAIL if ANY blocking gate has issues. Attempt safe fixes and re-run validation; stop only under the PASS, max-iterations, or unfixable-plan conditions in the Iteration Loop.
This review ensures nine critical properties of the task graph:
Why this matters: Prevents "done on paper" situations where the epic closes but key acceptance criteria are still unimplemented. Without this check, you can complete 100% of tasks and still have an incomplete feature.
Ensure that completing ALL tasks results in completion of the plan:
Why this matters: Silent rewrites of requirements cause implementation drift even when all tasks are closed.
Verify that:
Why this matters: Prevents parallel agents from conflicting on the same files and ensures prerequisites are built before dependents. Incorrect dependencies cause merge conflicts, broken builds, and wasted agent work.
Tasks must have correct dependency relationships:
File Overlap Dependencies:
Changes section for file pathsLogical Dependencies:
Why this matters: Each task description is the implementation agent's prompt. Strong coding-agent prompts read like good engineering tickets: outcome, what good means, constraints, verification, and expected completion response. Vague tasks cause rework; over-scripted tasks bury the product contract under generic process instructions.
Each task must be completable by an agent with no external clarification:
Prompt Shape:
Context Sufficiency:
Done Criteria:
Scope Clarity:
Why this matters: Ensures tasks follow the standard template so agents can reliably find required information. Missing sections are a common source of incompletable tasks.
Each task must include required sections:
plan.md#L45-L67). Multiple links when task spans multiple sections. "N/A" for spec if none exists.Plan Item(s) listing objective/AC/phase/obligation identifiers or quoted plan text the task owns, plus Infra/Support Justification set to N/A or explaining why setup/support work is necessary for mapped plan workConditional sections (required when applicable):
Source Document Links Validation:
**Source Documents**: section#L<start> or #L<start>-L<end>Spec Exists Rule: A spec exists if ANY of these are true:
*-spec.md file exists in the same directory as the planLine Number Validity Check:
Why this matters: Tasks exceeding size limits overwhelm agent context windows, leading to incomplete or incorrect implementations. AC count is a proxy for distinct obligations, not a formatting target; cosmetic bullet-packing makes tasks harder to implement and review.
Verify all tasks are within bounds:
| Limit | Standard Task | Mechanical Sweep |
|---|---|---|
| Files | ≤ 12 | ≤ 18 |
| Subsystems | ≤ 3 | = 1 |
| Acceptance Criteria | Preferred 1-3; hard max 5 atomic ACs when tightly coupled | Preferred 1-3; hard max 5 atomic ACs when tightly coupled |
Count atomic ACs, not bullets. A task with 3 bullets that each contain multiple unrelated checks may exceed the limit; a task with 5 crisp, tightly-coupled ACs may pass.
Mechanical sweeps additionally require:
Why this matters: Guarantees there are no dead or unreachable tasks and that work can actually flow from br ready to "plan complete". Orphan tasks waste effort; unreachable tasks never get done.
The task graph must be well-formed:
br ready via some sequence of dependency completionsWhy this matters: Enforces "red before green" and ensures tests accurately guard the intended behavior.
If using TDD ordering (per create-tasks):
[integration-path-test] taskWhy this matters: Prevents cross-layer gaps where changes are made in one layer but wiring in composition roots, adapters, or DI builders is never updated.
For tasks introducing new config/data/templates:
origin → transport → consumptionWhen create-tasks was used to generate the tasks, it produces specific artifacts that this review should consume:
| Artifact | Location | How to Use |
|---|---|---|
| Obligation Coverage table | In TODO.md or task descriptions | Cross-check against recomputed coverage; flag discrepancies |
| Propagation Map | In TODO.md or task descriptions | Use to verify wiring/adapter coverage checks |
| Sizing Summary table | In TODO.md | Compare against recomputed sizing; flag drift |
| AC Coverage table | In TODO.md | Verify AC→task mappings match |
If these artifacts exist, load them and verify consistency with recomputed state. Mismatches between artifacts and actual tasks indicate manual edits that may have introduced gaps.
State to build: plan_items, tasks
Determine task source:
--beads flag: Load from beads (br list --status open)TODO.md in plan directoryLoad the plan (required for coverage check):
--from-plan provided, use that pathdocs/ or ~/.claude/plans/Build task inventory:
tasks = [
{
id: "T001",
title: "...",
description: "...",
files: ["src/auth/session.ts", ...],
dependencies: ["T000"],
parent: "EPIC-001",
acceptance_criteria: ["AC1", "AC2"],
has_goal: true,
has_context: true,
has_verification: true,
...
},
...
]
State to update: coverage_map, issues
Goal: Verify that completing all tasks completes the plan—no stragglers.
Extract plan obligations:
plan_items = [
{ type: "objective", text: "User can reset password", source: "Context & Goals" },
{ type: "ac", text: "AC1: Email sent within 5 seconds", source: "AC Coverage" },
{ type: "phase", text: "Phase 2: Email integration", source: "High-Level Approach" },
{ type: "obligation", text: "MUST rate-limit to 3 requests/minute", source: "Technical Design" },
...
]
Map each plan item to tasks:
| Plan Item | Type | Owning Task(s) | Status |
|-----------|------|----------------|--------|
| "User can reset password" | objective | T003, T004 | ✓ Covered |
| "Email sent within 5 seconds" | ac | T005 | ✓ Covered |
| "Phase 2: Email integration" | phase | T004, T005 | ✓ Covered |
| "MUST rate-limit to 3/min" | obligation | ??? | ⚠ MISSING |
Check for orphan tasks (tasks with no plan mapping):
Flag coverage gaps:
Rollup verification:
Why: The other phases mostly check internal consistency (tasks map to plan items, deps acyclic, sections present, sizes within limits). A task graph can be perfectly self-consistent and uniformly wrong because every task inherited a false premise from the plan. This phase samples tasks and checks them against the actual repo/data, not the plan's prose. It is the gate that catches "looked rigorous, was ungrounded."
Take a representative sample — all foundation/skeleton/capstone tasks plus a spread of implementation tasks; for large graphs, ≥1 per subsystem and every [system-wiring]/"make-green" task — and verify:
[system-wiring] task depends only on already-built components. If turning the test green requires net-new construction, that construction must be separate task(s) the wiring task blocks on → BLOCKING.If the substrate cannot be inspected from the review environment, you MUST NOT emit a bare PASS: either FAIL, or label the verdict PASS (GROUNDING_UNVERIFIED) and list which premises went unchecked (mirrors the FORMAT_ONLY pattern — a caveated PASS is not a clean PASS and must not read as one). A clean PASS certifies internal consistency + sampled external grounding, never full external correctness.
State to update: file_task_map, dependency_graph, issues
Goal: Verify dependency correctness—file overlaps and logical ordering.
Build file→task mapping:
file_task_map = {
"src/auth/session.ts": ["T001", "T003"],
"src/auth/middleware.ts": ["T002"],
"src/api/routes.ts": ["T001", "T002", "T004"]
}
Flag file overlaps without dependencies:
Issue: T001 and T003 both touch src/auth/session.ts but have no dependency
Fix: br dep add T003 T001
Verify logical dependencies:
Reject invalid epic-boundary dependencies:
Detect cycles:
State to update: issues
Goal: Each task can be completed without external clarification and reads as a strong coder prompt, not a generic process script.
For each task, evaluate:
4a. Prompt Quality Checklist:
4b. Context Sufficiency Checklist:
4c. Done Criteria Checklist:
4d. Scope Atomicity Checklist:
Flag problematic tasks:
T003: INCOMPLETE — 4 issues
- [BLOCKING] Missing verification commands
- [BLOCKING] AC "looks good" is subjective → rewrite as measurable outcome
- [WARNING] References "the discussion" without context
- [BLOCKING] Contains generic process scaffolding not required by the product contract; replace with task-specific outcome/constraints/verification
State to update: issues
5a. Task Format Compliance:
For each task, verify required sections present:
| Task | Goal | Context | Scope | Changes | AC | Verification | Status |
|------|------|---------|-------|---------|-------|--------------|--------|
| T001 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | OK |
| T002 | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | FAIL |
Missing required section → BLOCKING
5b. Sizing Compliance:
Count atomic acceptance criteria, not rendered bullets. An atomic AC is one distinct observable success condition the implementer must satisfy or verify. Do not pass sizing by combining multiple independent checks into one bullet with semicolons, conjunctions, or paragraphs; that is cosmetic consolidation and is itself a sizing failure. Preserve clear one-check-per-line ACs unless you can genuinely remove duplication or merge inseparable sub-conditions into one observable outcome.
AC limits:
Build sizing summary table:
| Task | Files | Subsystems | ACs | Mechanical? | Status | Action |
|------|-------|------------|-----|-------------|--------|--------|
| T001 | 4 | 1 | 2 | No | OK | — |
| T002 | 8 | 2 | 5 | No | OK | 5 tightly-coupled ACs share one verification path |
| T003 | 14 | 4 | 2 | No | OVER | MUST split (>12 files, >3 subsystems) |
| T004 | 16 | 1 | 1 | Yes | OK | Mechanical sweep allowed |
| T005 | 5 | 1 | 6 | No | OVER | MUST split or genuinely reduce scope (>5 atomic ACs) |
| T006 | 5 | 1 | 3 bullets / 7 atomic | No | OVER | MUST split; semicolon-packing does not count |
Exceeds hard limits → BLOCKING
State to update: issues
6a. Graph Integrity:
br ready, trace which tasks can eventually be reached6b. TDD Compliance (if applicable):
[integration-path-test] task6c. Wiring & Config:
For tasks with new config/data/templates:
## Task Review Summary
**Source**: [TODO.md path] or [Beads]
**Plan**: [plan.md path]
**Total Tasks**: N
### 1. Plan Coverage
- Objectives: X/Y covered
- Acceptance criteria: A/B covered
- MUST/SHALL obligations: M/N covered
- Unmapped/unjustified tasks (no plan-item mapping and no infra/support justification): [list or "none"]
- **Status**: PASS / FAIL
### 2. Dependency Correctness
- File overlap violations: N
- Missing logical deps: N
- Long chains (advisory): [list or "none"]
- Circular dependencies: [list or "none"]
- **Status**: PASS / FAIL
### 3. Agent Completability
- Tasks missing context: [list or "none"]
- Tasks with vague verification: [list or "none"]
- Tasks with subjective ACs: [list or "none"]
- **Status**: PASS / FAIL
### 4. Task Format Compliance
- Tasks missing required sections: [list or "none"]
- **Status**: PASS / FAIL
### 5. Sizing Compliance
- Tasks exceeding limits: [list or "none"]
- **Status**: PASS / FAIL
### 6. Graph Integrity
- Unmapped/unjustified tasks: [list or "none"]
- Unreachable tasks: [list or "none"]
- Potential duplicates: [list or "none"]
- **Status**: PASS / FAIL
### 7. TDD Compliance
- Features missing integration tests: [list or "N/A"]
- Ordering violations: [list or "none"]
- **Status**: PASS / N/A
### 8. Wiring & Config
- Tasks missing config override tests: [list or "N/A"]
- Tasks missing wiring maps: [list or "N/A"]
- **Status**: PASS / N/A
---
## Verdict: PASS / FAIL / FAIL (MAX_ITERATIONS_REACHED)
### Blocking Issues (must fix)
1. [Issue description + fix]
2. ...
### Warnings (should fix)
1. [Issue description + fix]
2. ...
### Iteration Notes
- **Iterations used**: N
- **Fixes applied**: [summary of fixes by category]
### Machine-Readable Verdict (JSON)
```json
{
"verdict": "PASS",
"iterations_used": 2,
"blocking_issue_count": 0,
"warning_count": 1,
"total_tasks": 12
}
### Detailed Findings Format
For each issue found:
```markdown
#### Issue: [Category] - [Brief Description]
**Severity**: BLOCKING / WARNING
**Tasks Affected**: T001, T003
**Problem**: [What's wrong]
**Why it matters**: [Impact if not fixed]
**Fix**: [How to fix it]
Example fix (if beads):
```bash
br dep add T003 T001 # T001 must complete before T003
---
## Worked Examples
### Example: PASS Report
```markdown
## Task Review Summary
**Source**: Beads (cerberus epic)
**Plan**: docs/password-reset-plan.md
**Total Tasks**: 5
### 1. Plan Coverage
- Objectives: 2/2 covered
- Acceptance criteria: 4/4 covered
- MUST/SHALL obligations: 3/3 covered
- Orphan tasks: none
- **Status**: PASS
### 2. Dependency Correctness
- File overlap violations: 0
- Missing logical deps: 0
- Long chains (advisory): none
- Circular dependencies: none
- **Status**: PASS
[... all other sections PASS ...]
## Verdict: PASS
### Blocking Issues
None
### Warnings
1. T003 and T004 could potentially run in parallel if split by subsystem
This example shows the final output after internal iteration. Intermediate iterations are not printed.
## Task Review Summary
**Source**: Beads (oauth epic)
**Plan**: docs/oauth-plan.md
**Total Tasks**: 10
### 1. Plan Coverage
- Objectives: 3/3 covered
- Acceptance criteria: 7/7 covered
- MUST/SHALL obligations: 4/4 covered
- Orphan tasks: none
- **Status**: PASS
### 2. Dependency Correctness
- File overlap violations: 0
- Missing logical deps: 0
- Long chains: none
- Circular dependencies: none
- **Status**: PASS
[... all other sections PASS ...]
## Verdict: PASS
### Blocking Issues
None
### Warnings
1. Consider parallelizing T003/T004 if split by subsystem
### Iteration Notes
- **Iterations used**: 3
- **Fixes applied**:
- Iteration 1: Created T008 for missing "revoke tokens" objective, created T009 for missing "refresh token expiry" AC
- Iteration 2: Added dependency `br dep add T005 T002` (file overlap), split T003 into T003a + T003b (sizing)
- Iteration 3: Left T004's 5 clear ACs separate because they are tightly coupled and share one verification path; split T006 because it had 7 atomic ACs despite 3 rendered bullets
## Task Review Summary
**Source**: TODO.md
**Plan**: docs/oauth-plan.md
**Total Tasks**: 8
[... sections with issues ...]
## Verdict: FAIL (MAX_ITERATIONS_REACHED)
### Remaining Blocking Issues
1. **Circular dependency**: T007 ↔ T008 — cannot resolve without changing task boundaries
### Warnings
1. **Long chain**: T001→T002→T003→T004→T005→T006 (6 tasks) — consider restructuring for parallelism
### Iteration Notes
- **Iterations used**: 5 (max)
- **Fixes applied**: 12 issues resolved across 5 iterations
- **Escalation needed**: Remaining issues require plan-level changes
| Check | Severity | Pass Condition | Fix |
|---|---|---|---|
| No-Stragglers Invariant | BLOCKING | Completing all tasks = plan fully complete; no remaining work | Add missing tasks for uncovered plan items |
| Plan coverage | BLOCKING | Every objective/AC/obligation has owning task(s) | Add missing tasks |
| Task mapping | BLOCKING | Every task maps to plan item or justified as infra | Remove orphan tasks or add justification |
| AC ownership | BLOCKING | Each AC has exactly one primary owner task | Reassign ownership |
| Consistency audit / requirement freeze | BLOCKING | Requirements Snapshot, Consistency Audit, and Deviation Log are present; tasks preserve plan/spec requirements unless an approved deviation is logged | Add missing artifacts, rewrite tasks to match plan/spec, or log approved deviations |
| Premise grounding (sampled) | BLOCKING | Cited files/symbols/components a sampled task reuses exist and are reachable, OR are built by an earlier in-graph task it depends on (not silently to-build) | Add the missing build task + dependency; re-slice |
| Runnable verification | BLOCKING | Every acceptance check compares against a reference that exists and is computable at the task's scale (or a named tractable substitute) | Replace the unrunnable gate with a tractable reference |
| Build-before-wire | BLOCKING | No wiring/"make-green"/[system-wiring] task depends on not-yet-built components | Split out the construction; add dependency |
| Requirement applicability | BLOCKING when an emphasized hazard/requirement is exercised by no available input/fixture | Each emphasized hazard/requirement is exercised by an available input, or flagged untestable/vacuous | Add a triggering fixture, or drop/flag the requirement |
| File overlap deps | BLOCKING | Tasks sharing files have explicit dependency | Add dependency |
| No task→ancestor epic deps | BLOCKING | No task depends on its parent epic or any ancestor epic | Remove task→epic dependency; add same-epic task dependency or epic-to-epic dependency as appropriate |
| No cross-epic task deps | BLOCKING | Task dependencies do not cross parent epic/sub-epic boundaries | Remove cross-epic task edge; add epic-to-epic dependency or reparent/re-slice tasks |
| Epic dependency completeness | BLOCKING | Multiple epics/sub-epics with required ordering have explicit epic-to-epic dependencies | Add missing epic dependency |
| Circular deps | BLOCKING | Dependency graph is acyclic | Restructure dependencies |
| Sub-epic shape | WARNING unless it obscures executable ordering or creates unreachable work, then BLOCKING | Sub-epics contain multiple executable child tasks or materially improve review/execution clarity | Flatten one-task/cosmetic sub-epics into the parent epic unless external tracker constraints require them |
| Prompt quality | BLOCKING when outcome/success/constraints/verification are missing or ambiguous, or when generic process scaffolding is present without being required by the product contract | Rewrite as a compact engineering-ticket prompt: outcome, what good means, task-specific constraints, verification, completion response | |
| Context sufficiency | BLOCKING | Every task has clear goal + concrete Changes entries | Expand task description |
| Done criteria | BLOCKING | Every task has concrete verification commands | Add verification |
| Objective ACs | BLOCKING | All ACs are measurable and testable | Rewrite subjective ACs |
| Task format | BLOCKING | All required sections present | Add missing sections |
| Source document links | BLOCKING | Every task has **Source Documents**: with valid plan link(s), spec link(s) if spec exists per Spec Exists Rule, line numbers in #L<n> or #L<n>-L<m> format, and labels matching text actually present in referenced range | Add/fix links per Spec Exists Rule and Line Number Validity Check |
| Sizing: standard | BLOCKING | Tasks ≤ 12 files, ≤ 3 subsystems, ≤ 5 atomic ACs; 4-5 ACs require tight coupling and one coherent verification path; semicolon-packed bullets count by atomic checks | Split task or genuinely reduce scope; do not cosmetically combine ACs |
| Sizing: mechanical | BLOCKING | Mechanical sweeps: ≤ 18 files, = 1 subsystem, grep-able/scriptable pattern, scripted verification, ≤ 5 atomic ACs with 4-5 only when tightly coupled and sharing one coherent verification path | Split or reclassify |
| Reachability | BLOCKING | Every task reachable from br ready | Fix blocking dependencies |
| Integration path tests | BLOCKING when applicable | Each feature in a create-tasks/TDD graph has one [integration-path-test] task | Add integration path test task |
| TDD ordering | BLOCKING when applicable | Implementation tasks depend on the skeleton + [integration-path-test] task; final implementation task verifies all relevant tests pass | Add dependencies or final verification |
| Startup vs runtime verification | BLOCKING when applicable | Config/boot-time semantics have explicit load/startup-path verification | Add startup/load-path test |
| Config override tests | BLOCKING when applicable | New configurable values have override tests reaching runtime via the normal load/construction path | Add override test |
| Wiring maps | BLOCKING when applicable | New data/config/templates or cross-layer propagation have wiring maps and tasks covering each hop | Add wiring map, missing task, or dependency |
| System wiring coverage | BLOCKING when applicable | Each end-to-end flow has a dedicated [system-wiring] task | Add system-wiring task |
| Adapter/bridge coverage | BLOCKING when applicable | Field/DTO/config changes are mapped across all adapters, mappers, constructors, and DI builders | Add adapter/bridge task coverage |
| Template lifecycle | BLOCKING when applicable | New templates/resources are loaded, passed through, and used by runtime behavior | Add missing lifecycle coverage |
| Merge/precedence semantics | BLOCKING when applicable | Merge, override, precedence, and default behavior have explicit verification | Add merge/precedence tests |
| Negative cases | BLOCKING when applicable | Rejection, error, and invalid-input behavior has explicit verification | Add negative-case tests |
| Duplicates | WARNING | Each piece of work in exactly one task | Merge tasks |
After review PASSES:
/implement or manual workbr ready to see which tasks can start immediatelyAfter review FAILS:
Common fix commands (if using beads):
# Add missing dependency
br dep add <blocked-task> <blocker-task>
br dep add <blocked-epic> <blocker-epic>
# Update task description
br update <task-id> --description "..."
# Add missing task
br create "Task title" -p 1 --parent <epic-id> --description "..."
# View task for editing
br show <task-id>
The user needs a ready task graph, not a problem list. When a blocking issue is safely fixable in the active task artifact or tracker, apply the smallest safe fix, update review state, and re-check the affected gate plus global No-Stragglers/dependency checks. Do not ask the user to re-run /review-tasks.
Stop only when one of these is true:
When you encounter blocking issues, apply fixes to the artifact/tracker when safe, mirror them in review state, then re-validate the relevant gates:
| Issue Type | Fix Action |
|---|---|
| Sizing: files > 12 | Split task into 2+ tasks by subsystem; update tasks list and dependency_graph |
| Sizing: subsystems > 3 | Split task by subsystem boundary; target 1-2 subsystems per new task, with ≤ 3 as the hard limit when the task remains one coherent outcome |
| Sizing: ACs > 5 atomic checks | Split the task or genuinely reduce scope. You may merge duplicate or inseparable sub-conditions, but MUST NOT pass by packing independent checks into fewer bullets with semicolons/conjunctions/paragraphs. If a task has 4-5 atomic ACs and they are tightly coupled with one verification path, leave them as clear separate ACs and mark sizing OK. |
| Long chain (advisory) | Consider restructuring to allow parallelism; split middle tasks if beneficial |
| File overlap without dep | Add same-epic task dependency, or add an epic-to-epic dependency/reparent tasks when the overlap crosses epics |
| Cross-epic task dependency | Remove cross-epic task edge; add epic-to-epic dependency or reparent/re-slice so task deps stay within one epic |
| Circular dependency | Remove one edge; restructure task boundaries if needed |
| Poor task prompt quality | Rewrite task description into outcome / what-good-means / task-specific constraints / verification / completion response. Remove generic process scaffolding unless exact process is required. Keep detailed implementation sequence only when order, API shape, migration sequencing, or safety constraints matter. |
| Missing plan coverage | Add new task to tasks list for uncovered objective/AC/obligation |
| Orphan task | Add plan mapping justification or remove from tasks |
| Missing verification | Update task in tasks with concrete verification commands |
| Subjective AC | Rewrite AC in task with measurable, testable criteria |
| Missing required section | Update task in tasks with the missing section |
| Missing/invalid source document links | Add **Source Documents**: section; each link must have #L<n> line numbers and a label matching content at those lines; include spec links if spec exists per Spec Exists Rule, else "Spec: N/A" |
Beads mode: execute br fixes when tooling is available, then refresh task/dependency state. When creating new epics/tasks during fixes, add dependencies immediately after the dependent issue is created and the blocker ID is known; do not create all issues first and batch all dependencies at the end. Include applied commands in ### Iteration Notes.
br dep add <blocked> <blocker>
br update <task-id> --description "..."
br create "Task for uncovered AC" -p 1 --parent <epic> --description "..."
TODO.md/team-task mode: edit the file directly by splitting/narrowing tasks, updating dependencies, genuinely consolidating duplicate/inseparable ACs, rewriting subjective ACs, adding missing sections, or inserting missing tasks. Do not cosmetically combine distinct ACs to reduce bullet count. For team-task files, update both the parser-owned meta block's depends: [...] field and the human-readable ### Dependencies section.
Plan-only or unfixable cases: do not invent new requirements. Report the blocker as requiring plan/user input.
Task Review Summary for the last iteration.### Iteration Notes with iterations used and the main fix categories or commands applied.Some blockers may be inherent to the plan structure and unfixable without changing the plan. In these cases, document an ACCEPTED DEVIATION with justification and continue only if all remaining gates pass.
Example:
### Accepted Deviations
1. **Long sequential chain**: The auth flow has inherent sequential dependencies
(token → session → permission → access → audit). Parallelization would require
plan changes. Accepted as structural constraint.
FORMAT_ONLY, and do not report PASS for full task-graph validity.--beads if beads database exists and has open tasksUse the large-graph handling from the prompt contract. Additionally:
in_progress status