| name | gas-plan |
| description | Dual-perspective GAS plan review (frontend + backend) with iterative convergence loop.
54 GAS-specific questions covering MCP workflow, CardService, V8 parsing, OAuth, concurrency.
**AUTOMATICALLY INVOKE** when plan content signals GAS domain:
- Plan references .gs files, .html files in GAS context, or mcp__gas__ tools
- Plan modifies CommonJS modules, __events__, doGet/doPost, or addon code
- Plan uses mcp-gas-deploy or references a scriptId
**NOT for:** General plan review (use /review-suite:review-plan — it fires automatically before ExitPlanMode),
code review (use /gas-review), non-GAS plans.
**Explicit invocation:** `/gas-suite:gas-plan` — runs the full standalone 54-question GAS
review without review-plan's general quality layer. Use when you want GAS-domain-only
feedback, or before review-plan fires.
**mode parameter:**
- `standalone` (default): TeamCreate + parallel evaluators + convergence loop + ExitPlanMode
- `evaluate`: Single-pass read-only evaluation — returns findings via SendMessage to a calling
team-lead. No edits, no team creation, no ExitPlanMode. Available for future integration
with review-plan (currently not wired).
|
| model | claude-sonnet-4-6 |
| allowed-tools | all |
GAS Plan Review: Iterative Convergence Loop
You review implementation plans from two perspectives per pass: frontend engineer (HTML/CSS/UX) and GAS engineer (backend/infrastructure). Both perspectives evaluate in parallel each convergence pass via spawned evaluator agents.
Evaluate mode (used internally by review-plan) is handled by EVALUATE.md — this file is standalone only.
Core Directive: Loop Until Stable
Loop until convergence. Do not output the final scorecard until exit criteria are met.
Step 0: Locate Plan and Load Context
- Plan file: Check skill arg. If empty, use
Glob("~/.claude/plans/*.md") and pick the most recently modified file. If no plan files exist, ask the user via AskUserQuestion.
- Standards context (cache for all passes):
- Read
~/.claude/CLAUDE.md
- Find and read the project memory file:
Glob("~/.claude/projects/*/memory/MEMORY.md") → read most recently modified
(skip gracefully if none found)
- Path variables (substitute into evaluator prompts at spawn time, same as
<plan_path>):
<questions_path>: ~/.claude/skills/gas-plan/QUESTIONS.md
(~ makes this portable across users; update here if install base changes)
- Read the plan and identify domains present (UI changes? new files? deployment? common-js edits?) for triage.
Team Setup
At the start of standalone mode (before the loop):
timestamp = Date.now()
team_name = "gas-plan-" + timestamp
TeamCreate({team_name, description: "GAS plan review — parallel frontend + GAS evaluators"})
Error Handling
Wrap the entire convergence loop in error handling:
IF any unrecoverable error occurs during the convergence loop:
1. Send shutdown_request to any active evaluator agents
2. TeamDelete
3. Surface the error to the user via AskUserQuestion
Do not leave orphaned team processes.
Perspective Assignments
Each question is owned by one perspective or shared. Tags: [F] = Frontend, [G] = GAS, [Shared] = both.
Frontend evaluator — HTML/CSS/UX focus:
- Primary: Q14, Q30, Q31, Q32, Q33, Q34, Q35, Q36
- Shared (frontend lens): Q13, Q15, Q16, Q27, Q28, Q38, Q41
- Note: Q43 (plan legibility) is evaluated post-loop, not by this evaluator during convergence passes.
GAS evaluator — backend/infrastructure focus:
- Primary: Q1-Q12, Q17-Q26, Q29, Q37, Q39-Q40, Q42, Q44, Q45, Q46, Q47, Q48, Q49, Q50, Q51, Q52, Q53, Q54
- Shared (backend lens): Q13, Q15, Q16, Q27, Q28, Q38, Q41
Shared questions (Q13, Q15, Q16, Q27, Q28, Q38, Q41): Both evaluators report on these. Team-lead merges: combine findings, keep the more actionable wording. Q47 (card navigation) is a Gmail-domain GAS-primary question — not in the shared list above. GAS evaluator covers it when active (bulk N/A when no Gmail add-on); frontend evaluator covers it only in the GAS-skipped fallback (see triage shortcut below).
Triage shortcut — evaluator skip:
- No UI/HTML/CSS changes → skip frontend evaluator entirely. Mark all frontend-owned questions N/A in pass summary (Q14, Q30-Q36; Q43 is post-loop and not part of convergence pass scoring). Shared question coverage: GAS evaluator evaluates all 7 non-Gmail shared Qs from both lenses (Q13, Q15, Q16, Q27, Q28, Q38, Q41 — Q47 only when Gmail add-on present; see GAS evaluator prompt fallback instruction).
- No .gs/deployment/common-js changes → skip GAS evaluator entirely. Mark all GAS-owned questions N/A in pass summary. Shared question coverage: frontend evaluator evaluates all 7 non-Gmail shared Qs (Q13, Q15, Q16, Q27, Q28, Q38, Q41 — Q47 is Gmail-domain, skip when no Gmail add-on; if Gmail add-on IS present and GAS evaluator is skipped, frontend evaluator also evaluates Q47 from both lenses; see frontend evaluator IMPORTANT block).
Triage shortcut — question-level bulk N/A: No new CSS → mark Q34 N/A without individual evaluation. No new interactive elements → mark Q31 N/A. No Gmail add-on/CardService patterns → bulk N/A Q44-Q48 (Q47 is GAS-primary, not a shared question — Gmail-domain bulk N/A applies here). All other shared questions are never bulk-N/A'd.
Never-N/A exception: Q1, Q2, Q42 are marked "never N/A" and are evaluated regardless of domain triage. If the GAS evaluator is skipped, the team-lead evaluates Q1, Q2, Q42 directly before the merge step.
Execution Flow
STEP 0: (done — plan loaded, team created)
plan_path = <absolute filesystem path resolved in Step 0>
team_name = <team_name created above>
pass_count = 0
prev_needs_update_count = null; prev_needs_update_set = []
pass1_needs_update_set = [] # snapshot after pass 1 for resolved_questions computation
total_changes_all_passes = 0 # running sum; increment by changes_this_pass after each pass's edits
gas_memoized_questions = set() # Q1, Q2, Q42 once confirmed stable PASS/N/A
gate1_gas = {"Q1", "Q2", "Q13", "Q15", "Q18", "Q42"} # defined once; used in stability-memoization check
gas_memoized_since = {} # pass_count when each was memoized
prev_gas_results = {} # Q-ID → PASS/NEEDS_UPDATE/N/A from previous pass (for stability-based memoization)
spawned_evaluators = [] # names of agents actually launched (for precise teardown)
results = {} # maps Q-ID → "PASS" | "NEEDS_UPDATE" | "N/A" — rebuilt each pass
user_already_asked_gate1 = false # prevents asking user twice at pass_count >= 5
incomplete_had_needs_update_last_pass = false # set per-pass; prevents false convergence when Incomplete evaluator had NEEDS_UPDATE last pass
memo_file = "~/.claude/.gas-plan-memo-" + timestamp + ".json"
# memo_file: checkpoint written after each pass for context-compression resilience.
# If state is lost mid-loop (long reviews): re-read memo_file at start of next pass.
Substitute plan_path, team_name, and questions_path (all derived in Step 0) into all evaluator prompts below before spawning.
DO:
-- Context-compression recovery: if memoized state appears lost, restore from checkpoint --
_recovered_this_pass = false
IF memo_file exists AND gas_memoized_questions is empty AND prev_needs_update_count == null:
Read memo_file → restore gas_memoized_questions, gas_memoized_since,
prev_needs_update_count, prev_needs_update_set, pass_count,
prev_gas_results (default {} if missing)
_recovered_this_pass = true
Print: "⚠️ Context recovery: restored memoized state from checkpoint (pass [pass_count])"
IF NOT _recovered_this_pass:
pass_count = pass_count + 1
CLEAR: current_needs_update_count = 0; current_needs_update_set = []; changes_this_pass = 0; incomplete_had_needs_update_last_pass = false
Print: "Pass [▓ × pass_count + ░ × (5-pass_count)] [pass_count/5]: evaluating..."
TRIAGE: Determine which evaluators are active based on domain analysis.
Print: " Spawning: " + (frontend active? "frontend" : "⏭️ frontend") + " · " + (gas active? "gas" : "⏭️ gas")
-- Memoized directive construction --
memoized_directive = ""
IF gas_memoized_questions is non-empty:
ids = comma-sep sorted Q-IDs from gas_memoized_questions (e.g. "Q1, Q2, Q42")
pass_notes = join([q + " (since pass " + gas_memoized_since[q] + ")" for q in sorted gas_memoized_questions])
memoized_directive = "Memoized questions — SKIP (stable PASS since pass [N]): " + ids + "\n(" + pass_notes + ")\nTreat as PASS in your output — do not re-evaluate."
(substitute actual pass numbers from gas_memoized_since[q_id] for each Q-ID before injecting)
[In a SINGLE message, spawn active evaluators as PARALLEL Task calls]
[Substitute the actual resolved plan_path and questions_path values into each prompt before spawning]
[If memoized_directive is non-empty, inject it into each evaluator prompt before the Constraints section]
[After spawning each evaluator, append its name to spawned_evaluators]
--- Frontend Evaluator Task ---
Task(
subagent_type = "general-purpose",
model = "claude-sonnet-4-6",
team_name = <team_name>,
name = "frontend-evaluator-p" + pass_count,
prompt = """
You are a senior frontend engineer evaluating a GAS implementation plan.
Your inputs:
- Question definitions: Read <questions_path> for the full question
table (questions marked [F] and [Shared])
- Standards: Read only the GAS Development and GAS Client-Server Patterns sections of
~/.claude/CLAUDE.md as needed (skip unrelated sections)
Evaluate these questions through the FRONTEND lens:
Frontend-owned: Q14, Q30, Q31, Q32, Q33, Q34, Q35, Q36
Shared (frontend lens): Q13, Q15, Q16, Q27, Q28, Q38, Q41
Note: Q43 (plan legibility) is evaluated post-loop — do not evaluate it here.
Triage: If plan has no UI/HTML/CSS changes → bulk N/A Q14, Q30-Q36.
Evaluate shared Qs regardless.
IMPORTANT — if GAS evaluator was skipped this pass (no .gs/deployment/common-js changes):
Also evaluate Q13, Q15, Q16, Q27, Q28, Q38, Q41 from the GAS engineering lens.
If the plan also contains Gmail add-on/CardService patterns, also evaluate Q47 from both lenses.
Output each shared question twice: first your frontend finding, then your GAS finding.
Label clearly: "[Frontend lens]" and "[GAS lens]". Team-lead merges both.
Self-referential protection: Skip content marked <!-- gas-plan --> or <!-- review-plan -->.
Output contract — call the SendMessage tool exactly once:
type: "message"
recipient: "team-lead"
summary: "Frontend evaluation complete — N NEEDS_UPDATE" (fill in count)
content: |
FINDINGS FROM frontend-evaluator
[Triage] ...
Q{N}: PASS | NEEDS_UPDATE | N/A — [one-sentence finding]
[EDIT: instruction if NEEDS_UPDATE]
(one entry per evaluated question)
Do not write findings to stdout — the team-lead only receives content via SendMessage.
[MEMOIZED_DIRECTIVE — team-lead injects memoized_directive here if non-empty.
This directive OVERRIDES the question list above — memoized questions are PASS
regardless of what the plan says. Do not re-evaluate them.]
Constraints:
- Do not use Edit, Write, or Bash tools — read-only evaluation
- Do not call ExitPlanMode or touch any marker files
- Call SendMessage exactly once with all findings
Plan to evaluate: <plan_path> — read it with the Read tool, then evaluate the questions above.
"""
)
--- GAS Evaluator Task ---
Task(
subagent_type = "general-purpose",
model = "claude-sonnet-4-6",
team_name = <team_name>,
name = "gas-evaluator-p" + pass_count,
prompt = """
You are a senior GAS backend engineer evaluating a GAS implementation plan.
Question definitions: Read <questions_path> for the full question
table (questions marked [G] and [Shared]) — includes GAS Gotchas reference.
Standards: Read only the GAS Development, MCP GAS Architecture, and GAS Client-Server
Patterns sections of ~/.claude/CLAUDE.md as needed (skip unrelated sections).
Evaluate these questions through the GAS engineering lens:
GAS-owned: Q1-Q12, Q17-Q26, Q29, Q37, Q39-Q40, Q42, Q44, Q45, Q46, Q47, Q48, Q49, Q50, Q51, Q52, Q53, Q54
Shared (GAS lens): Q13, Q15, Q16, Q27, Q28, Q38, Q41
Triage: If plan has no .gs/deployment/common-js changes → bulk N/A GAS-specific Qs.
If plan has no Gmail add-on/CardService patterns → bulk N/A Q44, Q45, Q46, Q47, Q48.
Evaluate shared Qs regardless (Q47 is GAS-primary, not shared — bulk N/A when no Gmail).
If frontend evaluator was skipped this pass (no UI/HTML/CSS changes):
Also evaluate Q13, Q15, Q16, Q27, Q28, Q38, Q41 from the FRONTEND lens.
Output each shared question twice: first your GAS finding, then your frontend finding.
Label clearly: "[GAS lens]" and "[Frontend lens]". Team-lead merges both.
Self-referential protection: Skip content marked <!-- gas-plan --> or <!-- review-plan -->.
Output contract — call the SendMessage tool exactly once:
type: "message"
recipient: "team-lead"
summary: "GAS evaluation complete — N NEEDS_UPDATE" (fill in count)
content: |
FINDINGS FROM gas-evaluator
[Triage] ...
Q{N}: PASS | NEEDS_UPDATE | N/A — [one-sentence finding]
[EDIT: instruction if NEEDS_UPDATE]
(one entry per evaluated question)
Do not write findings to stdout — the team-lead only receives content via SendMessage.
[MEMOIZED_DIRECTIVE — team-lead injects memoized_directive here if non-empty.
This directive OVERRIDES the question list above — memoized questions are PASS
regardless of what the plan says. Do not re-evaluate them.]
Constraints:
- Do not use Edit, Write, or Bash tools — read-only evaluation
- Do not call ExitPlanMode or touch any marker files
- Call SendMessage exactly once with all findings
Plan to evaluate: <plan_path> — read it with the Read tool, then evaluate the questions above.
"""
)
Wait for all active evaluator messages (90s reminder; after 120s total mark ⚠️ Evaluator Incomplete for any non-responding evaluator and proceed with available findings).
Incomplete evaluator rule: An Incomplete evaluator contributes ZERO changes and ZERO findings
to this pass. Pass CAN converge if responding evaluators returned 0 NEEDS_UPDATE AND the
Incomplete evaluator returned 0 NEEDS_UPDATE in the immediately prior pass. If the Incomplete
evaluator had NEEDS_UPDATE last pass: do NOT converge; spawn it again next pass.
Incomplete state tracking:
IF any evaluator was marked ⚠️ Evaluator Incomplete this pass:
incomplete_evaluator_qs = [questions owned by the incomplete evaluator(s)]
IF any q in incomplete_evaluator_qs is in prev_needs_update_set:
incomplete_had_needs_update_last_pass = true
-- Merge & Consolidate --
COLLECT all NEEDS_UPDATE from both evaluator messages
BUILD results dict:
results = {} # reset first — Never-N/A override runs after this, so its writes survive
For each question reported by any evaluator this pass:
results[q_id] = the status it reported ("PASS", "NEEDS_UPDATE", or "N/A")
For questions not covered by any active evaluator (triage-skipped evaluator):
results[q_id] = "N/A"
For already-memoized questions: results[q_id] = "PASS" (carried forward from gas_memoized_questions)
-- Never-N/A override (runs after BUILD so writes survive to memoization update) --
never_na_findings = []
IF GAS evaluator was skipped this pass (no .gs/deployment/common-js changes):
FOR q_id IN ["Q1", "Q2", "Q42"]:
IF q_id in gas_memoized_questions:
results[q_id] = "PASS" # already set by BUILD above; confirming invariant
CONTINUE
# Not memoized — evaluate directly:
IF q_id == "Q1": check — does the plan name a branch and include a push-to-remote step? (blocking)
IF q_id == "Q2": check — do the plan steps create a feature branch with incremental commits? (blocking)
IF q_id == "Q42": check — does the plan include a post-implementation review section (/review or /gas-review + build + tests)? (blocking)
Set results[q_id] = "PASS" or "NEEDS_UPDATE" based on the check above.
IF results[q_id] == "NEEDS_UPDATE": never_na_findings.append(q_id)
These three questions can never converge as N/A — any NEEDS_UPDATE here blocks exit.
For shared questions (Q13, Q15, Q16, Q27, Q28, Q38, Q41) — whether flagged by both
evaluators or reported with dual labels ([GAS lens]/[Frontend lens]) by a single evaluator
in the evaluator-skipped case:
Combine into single finding; keep the more actionable wording. (Rationale: "more actionable
wins" — both perspectives have domain-appropriate framing; choose clearest for implementer.)
For Q47 (GAS-primary, Gmail-domain) — only in the evaluator-skipped + Gmail-present case:
If frontend evaluator was skipped and Gmail add-on is present, frontend evaluator reported
Q47 with dual labels ([GAS lens]/[Frontend lens]). Combine into single finding, same rule.
In all other cases (both evaluators active, or no Gmail): Q47 is a single GAS finding only.
APPLY edits — for each [EDIT: ...] instruction in any evaluator message:
Call the Edit tool on the plan file to insert/modify the specified content.
Mark each insertion <!-- gas-plan -->.
Each Edit call = 1 change (increment changes_this_pass). Do not count findings you only described in text.
total_changes_all_passes += changes_this_pass
CONSOLIDATE plan (see Consolidation Rules below)
RE-READ consolidated plan
SET current_needs_update_set = (Q numbers flagged NEEDS_UPDATE from evaluator messages) UNION never_na_findings
SET current_needs_update_count = len(current_needs_update_set)
IF pass_count == 1: pass1_needs_update_set = current_needs_update_set[:] # snapshot for resolved_questions
PLATEAU = (prev_needs_update_count != null) AND (current_needs_update_count == prev_needs_update_count) AND (sameQNumbers(current_needs_update_set, prev_needs_update_set)) # set equality: order-independent; sameQNumbers = both arrays contain identical Q-number strings regardless of order
prev_needs_update_count = current_needs_update_count; prev_needs_update_set = current_needs_update_set
Print pass summary using per-pass template
-- Post-pass memoization update --
# Q1 + Q2: branching (additive-only — once branch + commits present, never removed)
FOR q_id IN ["Q1", "Q2"]:
IF results[q_id] in [PASS, N/A] AND q_id NOT in gas_memoized_questions:
gas_memoized_questions.add(q_id)
gas_memoized_since[q_id] = pass_count
# Q42: post-impl review section (additive-only — same reasoning as Q-NEW in review-plan)
IF results["Q42"] in [PASS, N/A] AND "Q42" NOT in gas_memoized_questions:
gas_memoized_questions.add("Q42")
gas_memoized_since["Q42"] = pass_count
# Stability-based memoization for Gate 2/3 questions (post-pass 2)
# If a Gate 2 or Gate 3 question returned PASS/N/A in BOTH the previous pass AND this pass
# (with plan edits applied between them), it's empirically stable — safe to memoize.
# Gate 1 questions are NEVER stability-memoized (too important to skip based on heuristic).
# gate1_gas defined in STEP 0 above — not redefined here.
IF pass_count >= 2:
FOR q_id in results:
IF q_id in prev_gas_results:
IF prev_gas_results[q_id] in [PASS, N/A] AND results[q_id] in [PASS, N/A]:
IF q_id NOT in gate1_gas:
IF q_id NOT in gas_memoized_questions:
gas_memoized_questions.add(q_id)
gas_memoized_since[q_id] = pass_count
prev_gas_results = results # Set LAST — after stability check reads it
-- Checkpoint: persist memoized state for context-compression resilience --
Write memo_file with JSON: {
pass_count, gas_memoized_questions: [...gas_memoized_questions],
gas_memoized_since, prev_needs_update_count,
prev_needs_update_set: [...prev_needs_update_set],
prev_gas_results
}
-- CONVERGENCE CHECK --
Gate1_unresolved = count of NEEDS_UPDATE on Q1, Q2, Q13, Q15, Q18, Q42 (all weight-3 questions)
IF pass_count >= 5:
IF Gate1_unresolved > 0:
IF NOT user_already_asked_gate1:
user_already_asked_gate1 = true
AskUserQuestion listing the unresolved Gate 1 questions.
Wait for user response.
IF user resolves: apply edits, re-evaluate (one final pass), update scorecard, then BREAK
IF user overrides: annotate scorecard with override, then BREAK
ELSE:
# Already asked once — do not ask again; break with current state
Print: "⚠️ Gate 1 unresolved after user response — breaking with REWORK rating."
BREAK
ELSE:
Print: "✅ Hard stop — max 5 passes reached, Gate 1 clear."
BREAK
IF Gate1_unresolved > 0:
CONTINUE (never exit with Gate 1 open, even if PLATEAU)
IF (PLATEAU OR current_needs_update_count == 0) AND NOT incomplete_had_needs_update_last_pass:
elapsed = Math.round((Date.now() - timestamp) / 1000)
IF pass_count == 1:
Print: "✅ Converged — no issues found (pass 1, [elapsed]s)"
ELSE:
resolved_questions = pass1_needs_update_set - current_needs_update_set
Print: "✅ Converged after [pass_count] passes ([elapsed]s | [total_changes_all_passes] total changes)"
IF resolved_questions is non-empty:
Print: "Resolved: [comma-separated resolved_questions sorted by ID]"
Print: "Gate 1: ✅ Clean | Gate 2: ✅ [n Gate2 PASS] PASS | Advisory: [n noted] noted"
BREAK
-- END CHECK --
WHILE TRUE (loop controlled by convergence check above)
OUTPUT final scorecard
# ⚠️ Do not execute teardown from here. Jump to "After Review Completes" section below.
# That section handles: Q43 post-loop evaluation → gate marker → teardown → ExitPlanMode.
# The TEARDOWN pseudo-block below is a conceptual placeholder only.
TEARDOWN: (see "After Review Completes" steps 2–5 for the actual teardown sequence)
Worked Example
Pass 1/5: evaluating...
[Spawning frontend-evaluator-p1 + gas-evaluator-p1 in parallel]
[frontend-evaluator-p1 findings]: 1 NEEDS_UPDATE (Q34) -- `.btn` conflicts with Google CSS
[gas-evaluator-p1 findings]: 3 NEEDS_UPDATE (Q1, Q9, Q19) -- no branch named, no merge strategy, no push-to-remote step; no deploy target; stub function
-> Build results: {Q34: NEEDS_UPDATE, Q1: NEEDS_UPDATE, Q9: NEEDS_UPDATE, Q19: NEEDS_UPDATE, Q2: PASS, Q42: PASS, ...}
-> Merge: shared Qs all PASS in both — no merge needed
-> Edits: add CSS namespace note (Q34), add branching section + merge strategy + push-to-remote + deployment target + implementation spec (Q1, Q9, Q19)
-> Consolidate: merge deployment + rollback into single section
-> Memoize post-pass: Q2 PASS → gas_memoized_questions={Q2}, Q42 PASS → gas_memoized_questions={Q2, Q42}
N/A: 12 | Stable PASS: 27 | ⏭️ Memoized: none
Pass 2/5: evaluating...
[Memoized directive injected: "Memoized questions — SKIP (stable PASS since pass 1): Q2, Q42 (Q2 since pass 1, Q42 since pass 1) — Treat as PASS in your output."]
[Spawning frontend-evaluator-p2 + gas-evaluator-p2 in parallel]
[frontend-evaluator-p2 findings]: 0 NEEDS_UPDATE
[gas-evaluator-p2 findings]: 1 NEEDS_UPDATE (Q12) -- incremental verification missing; Q2, Q42: PASS (memoized, skipped)
-> Build results: {Q12: NEEDS_UPDATE, Q1: PASS, Q2: PASS (memoized), Q42: PASS (memoized), ...}
-> Edit: add exec checkpoint after each push step
-> Consolidate: no duplicates found
-> Memoize post-pass: Q1 PASS → gas_memoized_questions={Q1, Q2, Q42}
N/A: 12 | Stable PASS: 30 | ⏭️ Memoized: Q2, Q42 (not re-evaluated this pass)
Pass 3/5: evaluating...
[Memoized directive injected: "Memoized questions — SKIP (stable PASS): Q1 (since pass 2), Q2 (since pass 1), Q42 (since pass 1)"]
[Spawning frontend-evaluator-p3 + gas-evaluator-p3 in parallel]
[frontend-evaluator-p3 findings]: 0 NEEDS_UPDATE
[gas-evaluator-p3 findings]: 0 NEEDS_UPDATE; Q1, Q2, Q42: PASS (memoized, skipped)
N/A: 12 | Stable PASS: 31 | ⏭️ Memoized: Q1, Q2, Q42 (not re-evaluated this pass)
-> CONVERGED at pass 3. Output final scorecard.
[Post-loop] Q43 evaluator spawned → PASS — steps are numbered, code blocks fenced.
Organization Quality (Q43): PASS
Exit Criteria (Gate-Based)
- Gate 1 (blocking, weight 3): All must PASS. Loop until satisfied. If persistent after edits, ask the user for resolution before stopping.
- Gate 2 (important, weight 2): Must stabilize (no new findings between passes). Loop until stable.
- Gate 3 (advisory, weight 1): Note findings but do NOT loop on them.
- N/A counts as PASS for gate evaluation. A weight-3 question marked N/A does not block.
- Plateau: NEEDS_UPDATE count unchanged between passes = stop (Gate 2 only; Gate 1 uses ask-user).
- Safety cap: 5 passes.
Ambiguity Handling
- Cannot determine PASS vs NEEDS_UPDATE? Ask the user via AskUserQuestion. Do not guess.
- Insufficient context to evaluate? Ask the user what information is needed.
- Edge case on advisory (weight 1)? Default to PASS. Do not generate false positives on low-weight questions.
Self-Referential Protection
See shared/self-referential-protection.md — read at ~/.claude/skills/shared/self-referential-protection.md (skip gracefully if not found) for the canonical protection policy.
If shared file is not found, use inline policy: mark all <!-- gas-plan --> content as review metadata, not production code; do not re-evaluate it. Do not flag review-added sections as needing tests (Q11), impact analysis (Q18), implementation (Q19), dead code removal (Q20), duplication checks (Q39), state edge cases (Q40), or integration checks (Q41).
Consolidation Rules (Every Pass)
After edits, consolidate. Specific criteria:
- Merge sections covering the same concern (e.g., separate "Deployment" and "Rollback" into one section)
- Remove redundant notes that repeat what the plan already says
- Each finding adds at most 2-3 sentences. Consolidation removes at least as much text as it adds (from pass 2 onward; pass 1 focuses on additions only).
- If plan is growing, prioritize: keep blocking findings, summarize important, drop advisory notes
- Plan gets cleaner each pass, not longer
- Keep-exemption: Content annotated with
<!-- keep: [reason] --> is EXEMPT from consolidation removal. Never remove or trim <!-- keep: --> content based on length heuristics.
- "Key flow" definition: Any implementation step, ordering dependency, error path, rollback step, or verification checkpoint. Prose trimming is OK. Removing or merging steps is NOT.
- Regression check (before RE-READ): Verify no key flow, corner case, or condition was removed during this pass. If any was dropped — even to reduce length — restore it and annotate with
<!-- keep: [reason] -->. Trimming prose is fine; removing logic is not.
Key Questions
Each returns PASS / NEEDS_UPDATE / N/A.
Weights: 3 = blocking | 2 = important | 1 = advisory.
Quick-Reference Weight Table
Gate 1 — Blocking (weight 3, must all PASS):
Q1 branching strategy [G] | Q2 branching usage [G] | Q13 standards [Shared] | Q15 simplicity [Shared] | Q18 impact analysis [G] | Q42 post-impl review [G]
(Note: When gas-plan runs inside review-plan as gas-evaluator, the effective IS_GAS Gate 1 also includes Q-G3 — evaluated by l1-evaluator, not gas-plan.)
Gate 2 — Important (weight 2, must stabilize):
Q3 sync [G] | Q4 folders+ordering [G] | Q5 right tools [G] | Q6 exec verify [G] | Q7 common-js sync [G] | Q9 deployment [G] | Q10 rollback [G] | Q11 tests [G] | Q12 incremental verify [G] | Q16 interfaces [Shared] | Q17 step ordering [G] | Q19 empty code [G] | Q20 dead code [G] | Q21 concurrency [G] | Q22 execution limit [G] | Q23 OAuth scopes [G] | Q24 idempotent [G] | Q27 input validation [Shared] | Q28 error handling [Shared] | Q29 logging [G] | Q32 event listeners [F] | Q38 unintended consequences [Shared] | Q39 duplication [G] | Q40 state-exists+absent [G] | Q41 bolt-on vs merge [Shared] | Q44 card structure [G] | Q45 action handlers [G] | Q46 token access [G] | Q47 navigation [G] | Q48 trigger coverage [G] | Q49 V8 parsing order [G] | Q50 namespace collision [G] | Q52 execution mechanism [G] | Q53 container-bound separation [G] | Q54 GCP project [G]
Gate 3 — Advisory (weight 1, note only):
Q8 isolated state [G] | Q14 naming [F] | Q25 quotas [G] | Q26 storage limits [G] | Q30 UX feedback [F] | Q31 accessibility [F] | Q33 error boundary [F] | Q34 CSS conflicts [F] | Q35 LLM comments [F] | Q36 breadcrumbs [F] | Q37 documentation [G] | Q43 plan legibility [F] [post-loop] | Q51 debug logging [G]
Triage shortcut — evaluator skip: See Perspective Assignments above. Shared questions are never bulk-N/A'd.
Triage shortcut — question-level bulk N/A: Bulk-mark specific questions N/A when clearly irrelevant (no UI changes → skip Q14, Q30-Q36; no new files → skip Q4; no deployment → skip Q10). Shared questions are never bulk-N/A'd. Note: Q43 is evaluated post-loop only — not during convergence passes.
Git & Version Control
Q1: Is there a branching/merging strategy? (3, GAS, never N/A)
All changes get a branch. Plan must name the branch, merge target, PR workflow, and merge
strategy (squash / rebase / merge commit). Push-to-remote step must be explicit.
Q2: Do the plan steps actually use branching? (3, GAS, never N/A)
Steps must create a feature branch and commit incrementally. Commit messages must follow
project conventions (conventional commits: feat/fix/chore/docs etc.). Risky changes must
include a git rollback path.
MCP GAS Workflow
Q3: Is local/remote file sync accounted for? (2, GAS)
mcp__gas__cat can return stale local. Specify remoteOnly: true for reads and verify after push. N/A: no remote file reads.
Q4: Are files in the right folders and in correct dependency order? (2, GAS)
Folders: addon code in inbox-crew/addon/, common modules in common-js/, HTML in html/, tests in test/. Order: require.gs at position 0, then base modules before consumers, tests last. Flag wrong folder placement or out-of-order dependencies. N/A: no new files.
Q5: Are the right mcp-gas-deploy tools used for each file type? (2, GAS)
HTML files must use write({..., raw: true}) (not plain write which adds CommonJS wrappers). .gs files use write without raw: true. cat paths must omit .gs extension. N/A: no file push/read operations.
Q6: Is there exec verification after each push? (2, GAS)
Each write (or write({..., raw:true})) must be followed by an exec to verify code loads. Push does not mean it works. N/A: no remote pushes.
Q7: If editing common-js modules, are mcp-gas-deploy templates also updated? (2, GAS)
CLAUDE.md: COMMON-JS_SYNC. Changes to shared modules must include dual updates. N/A: no common-js edits.
Q8: Does the plan account for GAS isolated execution state? (1, GAS)
Each exec() has isolated global state -- no persistence between calls. Data must go through Properties/Cache. N/A: no cross-exec state needed.
Q49: Does the plan respect V8 file parsing order? (2, GAS)
If any new file is added, or any file's position changes, verify that no loadNow module ends up with dependencies at higher file positions. loadNow modules must be positioned LAST, after all their transitive dependencies. Symptom of failure: "Module not found" at startup even though ls() shows the file exists.
N/A: plan adds no new files AND changes no file positions AND no loadNow modules exist in the project.
Deployment & Rollback
Q9: Is the deployment defined with target environment? (2, GAS)
GAS changes need push/deploy steps: write/write({...,raw:true})/rsync, exec verification, target env (dev/staging/prod). N/A: local-only files.
Q10: Is there a rollback plan if deployment goes wrong? (2, GAS)
Recovery path: revert commit + redeploy, versioned rollback, or hold previous deployment. Flag doGet/doPost/events changes without rollback note. N/A: no deployment.
Testing & Verification
Q11: Are tests updated for these changes? (2, GAS)
Interface changes need test updates. Bug fixes need regression tests. New functions need new tests. N/A: pure CSS/HTML visual changes.
Q12: Is there incremental verification at each step? (2, GAS)
Each step must have a checkpoint (exec, test, manual check). Flag all-testing-at-end. N/A: single atomic change.
For plans that modify sidebar/HTML files (sheets-sidebar/, common-js/html/): verification steps should reference the gas-sidebar skill procedures (launch sidebar → send prompt → wait for response → read response). A plan that says "open the sidebar and check it works" without citing the concrete gas-sidebar workflow is insufficient — the sidebar runs in a cross-origin iframe and requires specific DevTools automation patterns.
Standards & Conventions
Q13: Does the plan adhere to project standards and conventions? (3, Shared, never N/A)
CLAUDE.md: CommonJS wrappers, __events__, loadNow:true, write({..., raw:true}) for HTML, createGasServer/exec_api.
MEMORY.md: doGet null-return, result.error not result.success, ConfigManager namespaces.
Q14: Do new names follow existing codebase conventions? (1, Frontend)
Casing, module naming, config key patterns. N/A: no new names.
Simplicity & Architecture
Q15: Is this as simple as possible, but no simpler? (3, Shared, never N/A)
Over-engineering: unnecessary modules, premature abstractions, duplicated common-js logic, future-proofing.
Under-engineering: missing error handling on GAS APIs, missing null checks on sheet ops.
Q16: Are modified interfaces consistent with other interfaces? (2, Shared)
All callers identified and updated, return formats match siblings, events consistent. N/A: no export/signature changes.
Q17: Are step ordering and sequencing dependencies explicit? (2, GAS)
Clear DAG. Flag: refs to uncreated files, deploy before push, require() targets pushed after importers. N/A: single step.
Q41: Is the proposed change integrated into existing architecture or bolted on as an isolated addition? (2, Shared)
New code should extend existing modules, reuse existing patterns, and follow established data flows. Flag: new utility when an existing one covers the use case or could be extended; new file when an existing file handles the concern; new pattern when existing conventions already address it; additions that don't connect to the codebase's module structure or data flow. N/A: change is purely additive with no existing structure to integrate into.
Impact & Cleanup
Q18: Are there other impacted features not considered? (3, GAS)
Cross-ref changed modules against callers (grep require(), call sites, __events__). Flag unmentioned callers that may break. N/A: fully isolated, zero callers.
Q19: Is there any empty code that needs implementation? (2, GAS)
Flag stubs, TODOs, "implement later" without full spec. Allow explicitly phased delivery. N/A: no placeholders.
Q20: Is there dead code that should be removed? (2, GAS)
Old implementation marked for removal when replaced? Flag orphaned exports, unused handlers in changed modules. N/A: nothing replaced.
Q50: Does the plan introduce any GAS global namespace collision? (2, GAS)
Check: do any new or modified modules declare top-level vars/consts whose names match GAS built-in globals (Logger, Utilities, DriveApp, SpreadsheetApp, ScriptApp, UrlFetchApp, CacheService, PropertiesService, LockService, HtmlService, ContentService, MailApp, GmailApp, etc.)? loadNow modules are highest risk since they run at parse time. Also check require() aliases — const Logger = require(...) at module top level is safe; var Logger = ... outside a function is not.
N/A: plan adds no new modules AND no existing module is modified at its top-level scope.
Q51: Do new modules use the 3-param _main signature for debug logging? (1, GAS)
Any new CommonJS module (_main factory) should use function _main(module, exports, log). The log param is auto-injected by require.js and is a no-op when not enabled — zero runtime cost. Plans that include debugging/testing steps should also show how to enable it:
exec: setModuleLogging('folder/ModuleName', true) // enable during test
exec: setModuleLogging('folder/ModuleName', false, 'script', true) // disable after
N/A: plan adds no new CommonJS modules (no new _main factory files).
Q38: Are there unintended consequences from this plan that need to be addressed? (2, Shared)
Side effects beyond the stated goal: breaking existing workflows, changing user-facing behavior unintentionally, introducing performance regressions, altering data formats consumed by other systems, or shifting security boundaries. Flag anything the plan doesn't explicitly acknowledge. N/A: trivial isolated change with no external touchpoints.
Q39: Does the plan introduce logic duplicating existing implementations? (2, GAS)
Before adding new functions or modules, verify no equivalent already exists (grep callers, scan module registry). Flag plans that reimplement logic already in common-js or sibling modules without justification. N/A: no new functions or modules introduced.
Q40: Does the plan account for both state-exists and state-absent edge cases in persistent storage? (2, GAS)
State-exists risk: code that reads ConfigManager/Properties/Cache/Sheets and misinterprets values left by a prior version — old schema format, stale cache entry, conflicting user config from an earlier install. State-absent risk: code that reads state before it has ever been written — uninitialized ConfigManager/Properties key, cold Cache, missing sheet row or named range, first-run user. Flag: reads without null/existence check; writes that assume stored data is in the expected schema; feature paths with no initialization guard for first-run. N/A: plan introduces no reads from or writes to ConfigManager, Properties, Cache, Sheets, or any shared persistent storage.
Concurrency, Quotas & Runtime
Q21: Are there concurrency considerations? (2, GAS)
Shared state (Properties, Cache, sheets) needs locking. Triggers/background need concurrency plan. N/A: read-only, client-only.
Q22: Will the operation fit within the 6-minute execution limit? (2, GAS)
Batch ops, large sheet reads, chained APIs need runtime estimate and chunking. N/A: bounded quick ops.
Q23: Does the plan add new OAuth scopes? (2, GAS)
Adding scopes forces re-auth for all users. Note which APIs and user impact. N/A: no new GAS services.
Q24: Are operations idempotent -- safe to retry? (2, GAS)
Triggers/web apps can fire twice. Data mutations need dedup or check-before-write. N/A: read-only.
Q25: Are quota and rate limits accounted for? (1, GAS)
UrlFetch 20K/day, Properties 50 reads/min, runtime 6min, triggers 90min. N/A: no API/batch/trigger additions.
Q26: Are Properties/Cache payloads within actual limits? (1, GAS)
PropertiesService: 524,288 chars/value, 512KB total per store, 500 keys max. CacheService: 102,400 bytes/value, 250-char key max, FIFO eviction (not LRU — hot keys can still be evicted). Exceeding these silently fails or throws with no clear error. N/A: plan does not read/write PropertiesService or CacheService.
Security
Q27: Is input validated at trust boundaries? (2, Shared)
doGet/doPost params, form submissions, exec_api args need sanitization. Flag raw e.parameter, unescaped HTML, formula injection. N/A: no untrusted input.
Error Handling & Logging
Q28: Are errors handled gracefully with actionable messages? (2, Shared)
Try/catch on GAS APIs, user-facing messages (not stacks), fail-loud vs fail-silent noted. Consistent with ChatService format. N/A: no new error paths.
Q29: Is the logging strategy informative yet compact? (2, GAS)
setModuleLogging(pattern) over Logger.log(). Context without dumps. No sensitive data. N/A: no server logic changes.
UX & Frontend
Q30: Is there UX feedback during long operations? (1, Frontend)
Loading states, spinners, cancel support for >2s ops. N/A: no new UI server calls.
Q31: Are new UI elements accessible? (1, Frontend)
aria-* labels, tab order, focus management in iframes. N/A: no new interactive elements.
Q32: Are event listeners cleaned up to prevent memory leaks? (2, Frontend)
Sidebar reopens accumulate listeners. Flag setInterval, addEventListener without cleanup. N/A: no new listeners.
Q33: Is there a client-side error boundary for silent crashes? (1, Frontend)
window.onerror or try/catch around init. N/A: no new client logic.
Q34: Do new CSS styles avoid conflicts with Google's add-on CSS? (1, Frontend)
Namespace classes (.chat-btn not .btn). Avoid broad selectors. N/A: no new CSS.
LLM Maintainability
Q35: Are there token-optimized LLM comments where needed? (1, Frontend)
<!-- LLM: [module] [function] [5-8 word purpose] --> for WHAT. N/A: trivial/self-documenting.
Q36: Are there breadcrumb comments for non-obvious patterns? (1, Frontend)
WHY something exists: workarounds, undocumented behavior, intentional oddities. N/A: no non-obvious patterns.
Plan Legibility
Q43: Would any update materially improve plan legibility when run in Claude Code? (1, Frontend)
As a senior UI engineer running this plan in Claude Code: are steps numbered, are code blocks properly fenced, are section headers scannable, and are conditional branches (IF/ELSE) visually distinct? Flag plans with walls of prose, unnumbered multi-step sequences, or deeply nested logic that becomes hard to follow during execution. N/A: plan is a single atomic step or is already well-structured.
Gmail Add-On / CardService
Q44: Does the card structure follow stateless best practices? (2, GAS)
Cards must be rebuilt from scratch on each trigger invocation — CardService has no persistent card objects between calls. Evaluate: (a) State stored in PropertiesService or CacheService, not in card object references; (b) Cache keys use message-scoped prefixes (ctx_ + messageId, chat_ + messageId); (c) CacheService TTL appropriate to data lifetime (6 hours for classification, 1 hour for chat, 10 min for temp async state); (d) Async trigger pattern planned for long-running ops (LLM calls, external APIs) — saves state to PropertiesService, creates time-based trigger after 500ms, returns processing card with "Check Response" button, background fn saves result to CacheService, trigger cleaned up in finally block; (e) Trigger cleanup strategy explicit (user limit: 20 triggers; accumulation causes quota errors). Flag: mutable card references across invocations, global card caches, card.update() anti-patterns, missing trigger cleanup, LLM calls blocking the 30-second response limit without async pattern. N/A: no CardService usage in plan.
Q45: Are all card action handlers wired and exported? (2, GAS)
Every setOnClickAction, setOnChangeAction, setOnClickOpenLinkAction must reference a function that is globally visible or registered via __events__. Evaluate: (a) Action string in setFunctionName() matches an exported function name exactly (case-sensitive); (b) Handler functions in module.exports with __events__: true; (c) Parameters passed via setParameters({key: 'value'}) — strings only, objects must be JSON-serialized; (d) Parameter extraction uses e.commonEventObject.parameters.key; (e) Form inputs extracted safely: e.commonEventObject.formInputs[field]?.stringInputs?.value?.[0] with defaults; (f) Switch widgets set BOTH setValue('true') (submitted value) AND setSelected(boolean) (UI state); (g) ActionResponse pattern matches intent: pushCard for drill-down (adds back button), updateCard for refresh (no navigation change), popCard for back/cancel, popToRoot for reset after major action, setNotification for toast (mutually exclusive with navigation — navigation wins if both set). Flag: action string references non-exported function, handler names don't match any function in plan's file set, missing __events__: true, notification + navigation combined. N/A: no card actions in plan.
Q46: Is Gmail message access token handled correctly? (2, GAS)
GmailApp.setCurrentMessageAccessToken(e.gmail.accessToken) must be called as the FIRST line in every contextual trigger handler before any GmailApp.getMessageById() call. Evaluate: (a) Token set before ALL GmailApp operations in contextual handlers; (b) Token NOT cached across separate trigger invocations (isolated GAS state — caching breaks on new invocations); (c) Token NOT needed in homepage handlers (no e.gmail available there — accessing it crashes); (d) Draft creation uses message.createDraftReply() or message.createDraftReplyAll() for replies — NOT thread.createDraft() (creates new message, not reply); (e) Label operations use getOrCreate pattern: getUserLabelByName() then createLabel() if null (silent failure if label missing); (f) OAuth scopes in appsscript.json match actual operations: gmail.addons.execute, gmail.addons.current.message.readonly, gmail.modify (for drafts/labels/archive). Flag: missing token set before message access, token stored in Properties/global var for reuse across invocations, thread.createDraft() for replies, label ops without existence check, missing OAuth scopes for planned GmailApp operations. N/A: no Gmail message access in plan.
Q47: Is card navigation balanced (push/pop)? (2, GAS)
Every pushCard path must have a corresponding popCard, popToRoot, or explicit navigation reset path. Evaluate: (a) Detail/settings cards pushed via pushCard include a back button using popCard; (b) Navigation depth stays reasonable (3-4 cards max; ~10 card practical limit); (c) Major actions (send, archive, delete) use popToRoot to reset stack; (d) updateCard used for real-time refresh within a view (does not change navigation stack); (e) Error cards include back button — never dead-end the user; (f) No notification + navigation combined (navigation supersedes notification if both set). Flag: unbounded push depth without back navigation, pushed cards with no back button, orphaned card stacks (pushCard with no pop path), popCard called from card that was never pushed, using pushCard where updateCard is semantically correct (chat message refresh). N/A: single-card add-on with no navigation, or all interactions are updateCard only.
Q48: Are homepage and contextual triggers both covered? (2, GAS)
appsscript.json must declare both homepageTrigger (in addOns.common) and contextualTriggers (in addOns.gmail) when the add-on needs both entry points. Evaluate: (a) homepageTrigger.runFunction references an existing handler that does NOT access e.gmail (unavailable in homepage context); (b) Contextual trigger onTriggerFunction references an existing handler that calls setCurrentMessageAccessToken before any GmailApp use; (c) Handler functions check for e.gmail presence/absence when serving both contexts; (d) appsscript.json oauthScopes array includes all scopes needed by both trigger paths; (e) If compose trigger needed: composeTrigger section in addOns.gmail with selectActions; (f) If universal actions needed: universalActions section in addOns.gmail. Flag: missing trigger type in manifest for a planned entry point, homepage handler that crashes on missing e.gmail, contextual handler missing token set, function names in manifest don't match any planned function, OAuth scopes don't cover all planned Gmail operations. N/A: not a Gmail add-on (web app or Sheets-only).
Documentation
Q37: Does project documentation need updating? (1, GAS)
Identify affected project docs: MEMORY.md, CLAUDE.md, README, JSDoc. Update when: API behavior changes, new conventions established, module responsibilities shift, new config patterns added. N/A: no behavior/API changes.
Post-Implementation Review
Q42: Is there a plan to review all changes after all code is applied? (3, GAS, never N/A)
Plan must include a post-implementation section after all implementation steps:
(1) run /review or /gas-review — loop until clean,
(2) run build/compile if applicable,
(3) run tests.
Steps 4–5 of CLAUDE.md POST_IMPLEMENT (fail recovery and PR creation) apply at runtime regardless of plan text — plan does not need to restate them.
Ensures regressions and secondary issues are caught before closing out the task.
Mandatory for all plans — cannot be skipped.
Rating
| Rating | Criteria |
|---|
| READY | Gate 1 all PASS + Gate 2 all PASS |
| SOLID | Gate 1 all PASS + Gate 2 ≤ 2 NEEDS_UPDATE |
| GAPS | Gate 1 all PASS + Gate 2 > 2 NEEDS_UPDATE |
| REWORK | Gate 1 has any NEEDS_UPDATE |
Score
(PASS_weight_sum) / (applicable_max_weight_sum) * 100 — summary metric alongside gate rating.
Q43 (weight 1) is included in applicable_max_weight_sum once evaluated post-loop; its result is appended to the scorecard separately under "Organization Quality (Q43)" but counts toward the score.
Output Templates
Per-Pass Template
Show only NEEDS_UPDATE items and status changes since last pass. Summarize stable/N/A as counts.
## Pass [N]/5
N/A: [count] | Stable PASS: [count] | ⏭️ Memoized: [comma-sep Q-IDs, or "none"] (not re-evaluated this pass)
✅ frontend ✗[fn] ✓[fm] —[fk] (or: ⏭️ frontend skipped | ⚠️ frontend timeout)
✅ gas ✗[gn] ✓[gm] —[gk] (or: ⏭️ gas skipped | ⚠️ gas timeout)
| Evaluator | Q# | Question | Status | Notes |
|-----------|-----|----------|--------|-------|
| Frontend | Q34 | CSS conflicts | NEEDS_UPDATE | `.btn` conflicts with Google CSS |
| GAS | Q1 | Branching strategy | NEEDS_UPDATE | No branch named |
| GAS | Q12 | Incremental verify | PASS (was NEEDS_UPDATE) | exec checkpoint added |
**Result:** [count] NEEDS_UPDATE ([Q numbers]) -- Frontend: [n], GAS: [n]
**Frontend edits:** [list]
**GAS edits:** [list]
**Consolidation:** [what was merged/removed]
Final Scorecard
Rating: [🟢 READY / 🟡 SOLID / 🟠 GAPS / 🔴 REWORK] [N]%
Converged: [Yes pass N / No max 5 reached]
Gate 1 (blocking): [✅ PASS / ❌ n remaining]
Gate 2 (important): [✅ PASS / ❌ n remaining]
Gate 3 (advisory): [n noted]
Organization Quality (Q43): [PASS | NEEDS_UPDATE — reason | ⚠️ timed out] # appended by post-loop step 2; omit if N/A (< 3 steps)
After Review Completes (standalone mode only)
After outputting the Final Scorecard:
-
REWORK gate (handled inside the convergence loop — not a post-loop step): Gate 1 is
resolved by the pass_count >= 5 branch inside the loop. By the time the loop exits, Gate 1
is either clean or the user has been asked and responded. If Rating is REWORK when the loop
exits (user override or unresolvable): note the override in the scorecard. Do not re-run the
REWORK check here — it was already handled inside the loop.
-
Q43 post-loop evaluation (plan legibility / organization):
[Substitute plan_path and questions_path (resolved in Step 0) before spawning]
Spawn a single Task (general-purpose, current team_name):
name: "q43-evaluator"
prompt: Evaluate Q43 from <questions_path>.
Q43 checks: Are steps numbered? Are code blocks fenced? Are section headers scannable?
Are conditional branches (IF/ELSE) visually distinct? Are walls of prose present?
Skip content marked <!-- gas-plan --> or <!-- review-plan -->.
Return one of:
PASS — [one-sentence reason]
NEEDS_UPDATE — [specific edit instruction: what to add/change and where]
Send findings via SendMessage to team-lead (type: message, recipient: team-lead).
Plan to evaluate: <plan_path> — read it with the Read tool, then evaluate Q43 above.
Append "q43-evaluator" to spawned_evaluators.
Wait for message (90s max). Timeout handling:
IF no response after 90s:
⚠️ Q43 Evaluator Incomplete — proceed without Q43 evaluation.
Add to scorecard: Organization Quality (Q43): ⚠️ Evaluator timed out — skipped
Continue to step 3.
IF NEEDS_UPDATE: apply one round of edits to the plan file.
Add Q43 result to the Final Scorecard output under a new line:
Organization Quality (Q43): [PASS | NEEDS_UPDATE — reason]
-
Use the Bash tool to run: slug=$(basename '<plan_path>' .md) && echo '<plan_path>' > ~/.claude/plans/.review-ready-"$slug" && rm -f <memo_file> — writes the slug-scoped gate file so ExitPlanMode will pass; second command removes the convergence checkpoint (no longer needed after loop exits)
-
Team teardown: Send shutdown_request to all agents in spawned_evaluators (only agents that were actually launched — triage-skipped evaluators and any agents not appended to spawned_evaluators are never targeted), then call TeamDelete. (Teardown must complete before ExitPlanMode — the session context needed for TeamDelete is not available after exiting plan mode.)
-
Call ExitPlanMode immediately. Do not pause, do not ask "should I present the plan?"
The PreToolUse hook on ExitPlanMode checks for the slug-scoped gate file (~/.claude/plans/.review-ready-{slug}) and blocks if not found. The PostToolUse hook deletes it on successful exit.
