Plan-checker: solve BLOCKER and WARNING iteratively in GSD

Among all the components of GSD, the plan-checker is that which has changed my workflow the most. Not because you always find dramatic things, but because you find exactly Those things that the planner forgot and you wouldn't have noticed until they exploded into execute. It returns plans that don't implode. Five minutes of checking saves you three hours of fixing during execute.

Independence Disclaimer: I am not affiliated with XPHX0XPHX or XPHX1XPHX. The description that follows is based on approximately sixty cycles of plan-checker I performed on my brownfield portfolio.

What does the plan checker do?

After the planner produced the NN-NN-PLAN.mdThe workflow process /gsd-plan-phase spawn a sub-agent gsd-plan-checker with read access to:

• All PLAN.md files from this phase.
• The CONTEXT.md file of the phase (user decision locked).
• The research document (output researcher).
• UI-SPEC.md and AI-SPEC.md if present.
• VALIDATION.md (Nyquist Sampling by Dimension).
• REQUIREMENTS.md (list of REQ-ID covered by phase).
• PROJECT.md (core value, global constraints).

Structured report with BLOCKER and WARNING for size. Example of output (summary):

## ISSUES FOUND

BLOCKER (3):
  1. SERIES-CCWF-12 dual-claim - dichiarato in entrambi 20-03 e 20-04 frontmatter
  2. 20-07 scope eccessivo - 6 task, 80h, 108k parole, ~80 file
  3. RESEARCH.md Open Questions non RESOLVED - 4 domande aperte non risolte

WARNING (5):
  1. VALIDATION.md frontmatter outdated (nyquist_compliant: false)
  2. D-04 deroga 18 cluster EN body auto-translate non documentata
  3. ContactController toolPrincipale enum Java/string mismatch frontend
  4. 20-04 Task 3 cornerstone content 3500+ parole stessa sessione (qualità a rischio)
  5. 20-03 ComparativeMatrixComponent rgba hardcoded viola CSS variable policy

Every issue has a file:line reference, affected size, severity, and an actionable fix hint.

The eight to eleven evaluated dimensions

1. Coverage of objectivesare they bringing it up to the level of the goal in this phase? Mapping goal element → plan task.
2. Requirement coverageAll the REQ-ID listed in the ROADMAP appear in the frontmatter requirements: Do you have at least one plan?
3. Decision coverageAre all D-XX values from the CONTEXT plus 8 D-EVAL reflected in AI-SPEC and UI-SPEC decision-making tasks?
4. Task qualityevery task has <read_first> +<acceptance_criteria> +<action> Do concrete identifiers exist? Perform a spot check of 3 tasks for each plan, sample 24. Total tasks.
5. Wave dependencies 1. Le dipendenze ondinate 2. Wave dependencies 3. Dipendenze ondate 4. Ondine dependencies 5. Wave dependencies 6. Dipendenze ondateIs the wave structure cyclic? Plan of the same wave have disjoint files?
6. Threat Model CoveragePlan that touches the surface Security-relevant have block <threat_model> What is your specific threat ID?
7. Must-haves Goal-BackwardEvery plan declares must-haves Derived from the phase goal? Not generic.
8. Scope sanity Note: Since there are no tokens to preserve in this case, I'll provide a direct translation: Scope sanityIs there a plan exceeding 5 tasks or ~80 files modified? If yes, use BLOCKER to split.
9. Reuse verificationDo you want me to translate the rest of the Italian text as well? If so, please provide it.
10. Claude MD compliancePlan rules respect global constraints (e.g. light theme only, no AWS, Ollama on-prem only, i18n Pattern A)?

Real example: Phase 20 iteration 1

Phase 20 (the phase that planned the editorial series you are reading) had iteration 1 with 3 BLOCKER + 5 WARNING. Summary:

BLOCKER 1RESEARCH.md had a section "Open Questions (for planner)" with 10 open questions, not marked as RESOLVED. The planner had implicitly resolved them (e.g. publishedAt was fixed to 2026-10-01T08:00:00Z in the frontmatter), but 4 questions remained without documented answers. Iter 2 added inline responses and marked the section "(RESOLVED 2026-05-21 - iter 2)".

BLOCKER 2SERIES-CCWF-12 (Comparative matrix component) was declared in both frontmatter of 20-03 (component) and 20-04 (data), creating dual-claim. Iter 2 removed CCWF-12 from 20-03 and left only in 20-04, adding explicit sticky/accordion mobile test in 20-03 spec.

BLOCKER 3Plan 20-07 had 6 tasks, 80h estimate, 108k words content, ~80 files. Sanity check scope failed (threshold 5 tasks / 80 files = BLOCKER). Iteration 2 split into 20-07A (build pipeline + OSS) + 20-07B (cluster 01-09) + 20-07C (cluster 10-18 + linking) 10 total plans, each within a healthy scope.

Total time to solve the 3 BLOCKER: iteration 2 required 30 minutes of re-spawn planner Opus. Without checking, I would have gone into execute mode with Plan 20-07 which probably would have failed at the middle of Wave 4, costing me hours of debug + emergency replanning.

The revision loop in practice

Typical workflow with a plan-checker active:

1. /gsd-plan-phase N
2. Researcher spawned → RESEARCH.md product.
3. Plan generator → N Plan.md products.
4. Plan checker spawns → reviews.
5. Se ## GOAL_METAll blockers pass, warning tolerable. Workflow closes.
6. Se ## BLOCKERlist BLOCKER structured workflow. Decision is requested: retry (respawn planner with revision context) or stop.
7. On retry: iteration 2 spawns the planner with instructions mirrored ("fix BLOCKER 1+2+3 for instructions X, preserve rest"). The planner produces an updated plan.
8. Plan checker re-spawns on revised plans. Re-evaluation.
9. Maximum iterations 3. After iteration 3 with BLOCKER still open: force-approve / edit / abandon.

On my 19-phase project portfolio distribution iterations:

• Iteration 1 Goal MET Direct: ~30% (6 phases).
• Iteration 2 Goal after Blocker Fix: ~60% (12 Phases).
• Iteration 3 Goal after double review: ~10% (1 phase).
• Iteration 3 with UNRESOLVABLE BLOCKER: 0.

Which BLOCKERs recur most?

Frequent patterns on my portfolio:

1. Uncovered requirementThe planner forgot to map an XPHX0XPHX to a plan. Typically because the XPHX0XPHX was ambiguous or the CONTEXT did not emphasize it.
2. Excessive scopePlan with 6+ tasks. Cause: description Phase too long, or feature naturally bulky that had to be split into multiple phases already at the level of the roadmap.
3. Circular wave dependencyPlan A depends on B because it has crossed dependencies of Plan without noticing the loop.
4. Vague taskAction without concrete identifiers ("align with backend", "make it consistent"). Cause: The planner has produced a strategic-level action instead of a tactical one.
5. Empty threat modelPlan that modifies the surface authentication / payment / file upload without blocking threat model. Cause: The planner has underestimated the exposure to security.

What warnings occur most frequently?

1. Claude MD compliance softwareFor example, hardcoded CSS colors instead of CSS variables can be solved with small edits in the execute file.
2. Reuse missing referenceThe plan should cite PR of Phase previous with similar pattern. If omitted, the executor does not know that it exists analogically.
3. Scope risk borderlinePlan with 4-5 tasks but file Count is high. Typically a WARNING because the executor may degrade quality on a single task at the bottom.
4. Manual Checkpoint PlacementDeclared plan autonomous: true but include tasks that logically require human decision. WARNING to request a review.
5. Documentation drift remains a significant challenge in software development and testing. It refers to the phenomenon where documentation becomes outdated or diverges from the actual codebase, leading to confusion and errors among developers and testers. This can occur due to various reasons such as changes in project scope, new features being added, or even simple typos and formatting issues. To mitigate this issue, it is essential to maintain a high level of documentation quality and ensure that it aligns with the evolving codebase. This can be achieved through regular updates, reviews, and feedback mechanisms. Additionally, using version control systems and collaboration tools can help track changes and facilitate communication among team members. It's also important to note that documentation drift can have serious consequences, such as increased maintenance costs, reduced productivity, and even security vulnerabilities. Therefore, it is crucial to address this issue proactively and implement strategies to prevent it from occurring in the first place. Some best practices for managing documentation drift include: * Regularly reviewing and updating documentation * Using version control systems to track changes * Implementing feedback mechanisms to ensure accuracy and completeness * Utilizing collaboration tools to facilitate communication among team members By following these guidelines, developers and testers can minimize the risk of documentation drift and ensure that their documentation remains accurate, up-to-date, and effective.VALIDATION.md draft vs PLAN Final versions diverge. WARNING for alignment.

When XPHX0XPHX, XPHX1XPHX can be accepted

WARNING is not a BLOCKER: the workflow can proceed without resolving them, but it's an explicit choice. Typical cases of WARNING accepted:

• Warning on intentional patternsExample: duplication documented between computeTaxIt e computeTaxFr It's not duplication, it's two distinct functions for jurisdiction. I accept WARNING + document the reason in CONTEXT.md.
• Warning on scope risk at the border linePlan with 4-5 tasks, scope just at the limit. I proceed accepting the risk, monitoring if quality degrades. If yes, split into execute.
• Warning on explicit deductionsExample: D-04 says "IT+EN at launch" but the EN body cluster differs from Wave 5 auto-translate. Accepted WARNING after documenting deviations from the objective of the plan.

Anti-pattern: skip of the plan checker

The temptation to skip the check is strong: "I know I can handle the plan just fine." Error. I skipped for the first two months of GSD, ending up with Fix during execution. with costs 3-5 times higher than a check paid upfront.

Costo plan-checker: 5-10 minutes, ~15-30k tokens (on average). Cost of fix-during-execute for BLOCKER passed unnoticed: typically 30-90 minutes per BLOCKER, because the execute interrupts + requires replanning ad hoc + incomplete commits to rollback. The cost-benefit calculation is crystal clear.

Anti-pattern: revision without priority

When the check finds 5+BLOCKER, the temptation is to ask the planner "fix them all". Error: non-prioritized revision produces a plan that has been over-modified where the fix for BLOCKER 1 breaks the mitigation of BLOCKER 3.

Mitigation: in the prompt revision iteration 2, list BLOCKERs in priority + separate targeted fixes for blockers (e.g., "BLOCKER 1 fix: edit RESEARCH.md add RESOLVED; BLOCKER 2 fix: edit 20-03 frontmatter remove CCWF-12; ..." with concrete operational instructions instead of "fix the issues"). Planner produce an update mirated, no massive rewrite.

Integration with must-haves

Every plan declares must_haves front matter: truth Conditions that must be true at the end of the execute. Plan checker Verifies that must-haves are derived from the phase goal (goal backward check), not generic.

An illustrative example: Il nuovo modello di smartphone XPHX0XPHX è stato lanciato con grande successo in tutto il mondo. Il prezzo di listino è stato fissato a € 599, ma la versione speciale XPHX1XPHX è stata venduta a un prezzo più basso. The new model of smartphone XPHX0XPHX was launched with great success all over the world. The list price was set at € 599, but the special edition XPHX1XPHX was sold at a lower price.

must_haves:
  truths:
    - LeadMagnetController endpoint POST /api/v1/lead-magnets/{magnetId}/download
      restituisce 200 + PDF stream per magnetId ∈ enum whitelist (5 nuovi
      Phase 20 IDs)
    - Bucket4j rate limit 10 req/min per IP attivo su endpoint
    - ButtondownNewsletterAdapter.subscribeToListWithTags() chiamato
      atomically con download (testato in IT)
    - Test green: LeadMagnetIdPhase20Test + LeadMagnetControllerPhase20IT +
      PdfLeadMagnetRendererPhase20IT

These are truth verifiable post-execute, not aspirations. The verifier (gsd-verifier) checks them after the execute is completed.

What I learned writing this article

The main lesson is on skip costFor two months I thought the plan-checker was overhead. It was the thing that separated my stable workflow from my always-in-crisis workflow. Skip seems to make you earn five minutes, but actually it costs you ninety.

Second insight: the quality of the BLOCKERs found depends on the quality of the input. If CONTEXT.md is rich (27 D-XX well-articulated, like Phase 20), the check finds precise issues. If CONTEXT.md is poor (5 vague decisions), the check has no grip to be severe, and the plans pass with a BLOCKER-free but are still bad. Investing in discuss-phase pays off in plan-checker effectiveness.

Avoided pattern

• Skip "because I'm in a hurry"The speed is exactly the moment when the plan checker saves you from future debugging.
• General "fix all" revisionAlways prioritize, always with fixed instructions instead of problem description.

A story worth sharing

Placeholder Section If you have experience with the plan-checker that saved you (or did not find an important BLOCKER which then exploded), write to me at federico@federicocalo.devThe stories pseudonymized enter subsequent clusters.

Previous cluster: ROADMAP-driven planning Next cluster: Agent orchestration →