**Rounds completed**: {{CURRENT_ROUND}} of {{MAX_ITERATIONS}}
Before the loop fully exits, please perform a methodology improvement analysis. This analysis helps improve the Humanize development methodology itself -- it is NOT about the project you just worked on.
## Instructions
### 1. Spawn an Opus Agent for Sanitized Analysis
Use the Agent tool with `model: "opus"` to spawn an analysis agent. Give it this task:
**Agent prompt**: Read the development records in `{{LOOP_DIR}}`:
- All files matching `round-*-summary.md`
- All files matching `round-*-review-result.md`
Analyze these records from a **pure methodology perspective** and write your findings to `{{LOOP_DIR}}/methodology-analysis-report.md`.
**CRITICAL SANITIZATION RULES** - The report MUST NOT contain:
- File paths, directory paths, or module paths
- Function names, variable names, class names, or method names
- Branch names, commit hashes, or git identifiers
- Business domain terms, product names, or feature names
- Code snippets or code fragments of any kind
- Raw error messages or stack traces
- Project-specific URLs or endpoints
- Any information that could identify the specific project
**Focus areas for analysis**:
- Iteration efficiency: Were rounds productive or did they repeat similar work?
- Feedback loop quality: Did reviewer feedback lead to meaningful improvements?
- Stagnation patterns: Were there signs of going in circles?
- Review effectiveness: Did reviews catch real issues or create false positives?
- Plan-to-execution alignment: Did execution follow the plan or drift?
- Round count vs. progress ratio: Was the number of rounds proportional to progress?
- Communication clarity: Were summaries and reviews clear and actionable?
**Output format**: Write a structured report with methodology improvement suggestions. Each suggestion should describe a general pattern observed and a concrete improvement to the RLCR methodology. If no improvements are found, write a brief note saying the methodology worked well for this session.
### 2. Read the Analysis Report
After the agent completes, read `{{LOOP_DIR}}/methodology-analysis-report.md`. ALL subsequent user-facing content MUST be derived solely from this report -- do NOT reference raw development records directly.
### 3. Handle Results
**If no improvements found**: Briefly inform the user that the methodology analysis found no significant improvement suggestions. Then write a completion note to `{{LOOP_DIR}}/methodology-analysis-done.md` and exit.
**If improvements found**:
a) Report to the user:
- Brief summary of the exit reason ({{EXIT_REASON}}: {{EXIT_REASON_DESCRIPTION}})
- Methodology improvement suggestions from the report
b) Use `AskUserQuestion` to ask if the user would like to help improve Humanize by opening a GitHub issue with these suggestions. Emphasize:
- This is completely voluntary
- The content is fully sanitized (no project-specific information)
- It helps improve the methodology for everyone
c) **If user declines**: Thank them, write completion marker to `{{LOOP_DIR}}/methodology-analysis-done.md`, and exit.
d) **If user agrees**:
- Draft a GitHub issue title and body from the analysis report
- Show the draft via a second `AskUserQuestion` for the user to review and confirm
- If confirmed: run `gh issue create --repo PolyArch/humanize --title "..." --body "..."`
- If `gh` is not available, provide the title and body so the user can create the issue manually
- Write completion marker to `{{LOOP_DIR}}/methodology-analysis-done.md` and exit
### 4. Completion Marker
You MUST write meaningful content to `{{LOOP_DIR}}/methodology-analysis-done.md` before exiting. This file signals that the analysis phase is complete. A brief summary of what was done (e.g., "Analysis complete, no suggestions" or "Analysis complete, issue filed") is sufficient.
Note: You MUST NOT try to exit by lying, editing loop state files, or executing `cancel-rlcr-loop`.
After completing the work, please:
0. If the `code-simplifier` plugin is installed, use it to review and optimize your code. Invoke via: `/code-simplifier`, `@agent-code-simplifier`, or `@code-simplifier:code-simplifier (agent)`
1. Commit your changes with a descriptive commit message
2. Write your work summary into @{{NEXT_SUMMARY_FILE}}
**IMPORTANT**: Codex has found Open Question(s). You must use `AskUserQuestion` to clarify those questions with user first, before proceeding to resolve any other Codex's findings.
Accumulated commits since loop start (oldest first):
```
{{COMMIT_HISTORY}}
```
### Recent Round Files
Read these files before conducting your review to understand the trajectory of work:
{{RECENT_ROUND_FILES}}
Use this history to identify patterns across rounds: recurring issues, stalled progress, or drift from the mainline objective. Weight recent rounds more heavily but watch for systemic trends in the full commit log.
**Your Task**: Review the historical review results, especially the **recent rounds** of development progress and review outcomes, to determine if the development has stalled.
**Signs of Stagnation** (circuit breaker triggers):
- Same issues appearing repeatedly across multiple rounds
- No meaningful progress on Acceptance Criteria over several rounds
- Claude making the same mistakes repeatedly
- Circular discussions without resolution
- No new code changes despite continued iterations
- Codex giving similar feedback repeatedly without Claude addressing it
**If development is stagnating**, write **STOP** (as a single word on its own line) as the last line of your review output @{{REVIEW_RESULT_FILE}} instead of COMPLETE.
## Part 6: Output Requirements
- If issues found OR any AC is NOT MET (including deferred ACs), write your findings to @{{REVIEW_RESULT_FILE}}
- Include specific action items for Claude to address, classified into:
- Mainline Gaps
- Blocking Side Issues
- Queued Side Issues
-**If development is stagnating** (see Part 4), write "STOP" as the last line
-**CRITICAL**: Only write "COMPLETE" as the last line if ALL ACs from the original plan are FULLY MET with no deferrals
- DEFERRED items are considered INCOMPLETE - do NOT output COMPLETE if any AC is deferred
- The ONLY condition for COMPLETE is: all original plan tasks are done, all ACs are met, no deferrals allowed
Claude should normally keep the **mutable section** of `goal-tracker.md` up to date directly. If Claude's summary contains a "Goal Tracker Update Request" section, or if you detect tracker drift during review, YOU must:
1.**Evaluate the tracker state**: Is the mutable section still aligned with the Ultimate Goal and current AC progress?
2.**If correction is needed**: Update @{{GOAL_TRACKER_FILE}} yourself with the requested changes:
- Move tasks between Active/Completed/Deferred sections as appropriate
- Add entries to "Plan Evolution Log" with round number and justification
- Add new issues to "Blocking Side Issues" or "Queued Side Issues" as appropriate
-**NEVER modify the IMMUTABLE SECTION** (Ultimate Goal and Acceptance Criteria)
3.**If you reject a requested tracker change**: Include in your review why it was rejected
Common update requests you should handle:
- Task completion: Move from "Active Tasks" to "Completed and Verified"
- New blocking issues: Add to "Blocking Side Issues"
- New queued issues: Add to "Queued Side Issues"
- Plan changes: Add to "Plan Evolution Log" with your assessment
- Deferrals: Only allow with strong justification; add to "Explicitly Deferred"
**IMPORTANT**: The original plan that Claude is implementing is located at:
@{{PLAN_FILE}}
You MUST read this plan file first to understand the full scope of work before conducting your review.
This plan contains the complete requirements and implementation details that Claude should be following.
Based on the original plan and @{{PROMPT_FILE}}, Claude claims to have completed the work. Please conduct a thorough critical review to verify this.
---
Below is Claude's summary of the work completed:
<!-- CLAUDE's WORK SUMMARY START -->
{{SUMMARY_CONTENT}}
<!-- CLAUDE's WORK SUMMARY END -->
---
{{COMMIT_HISTORY_SECTION}}
## Part 1: Implementation Review
- Your task is to conduct a deep critical review, focusing on finding implementation issues and identifying gaps between "plan-design" and actual implementation.
- Relevant top-level guidance documents, phased implementation plans, and other important documentation and implementation references are located under @{{DOCS_PATH}}.
- If Claude planned to defer any tasks to future phases in its summary, DO NOT follow its lead. Instead, you should force Claude to complete ALL tasks as planned.
- Such deferred tasks are considered incomplete work and should be flagged in your review comments, requiring Claude to address them.
- If Claude planned to defer any tasks, please explore the codebase in-depth and draft a detailed implementation plan. This plan should be included in your review comments for Claude to follow.
- Your review should be meticulous and skeptical. Look for any discrepancies, missing features, incomplete implementations.
- If Claude does not plan to defer any tasks, but honestly admits that some tasks are still pending (not yet completed), you should also include those pending tasks in your review.
- Your review should elaborate on those unfinished tasks, explore the codebase, and draft an implementation plan.
- A good engineering implementation plan should be **singular, directive, and definitive**, rather than discussing multiple possible implementation options.
- The implementation plan should be **unambiguous**, internally consistent, and coherent from beginning to end, so that **Claude can execute the work accurately and without error**.
## Part 2: Goal Alignment Check (MANDATORY)
Read @{{GOAL_TRACKER_FILE}} and verify:
1.**Acceptance Criteria Progress**: For each AC, is progress being made? Are any ACs being ignored?
2.**Forgotten Items**: Are there tasks from the original plan that are not tracked in Active/Completed/Deferred?
3.**Deferred Items**: Are deferrals justified? Do they block any ACs?
4.**Plan Evolution**: If Claude modified the plan, is the justification valid?
Include a brief Goal Alignment Summary in your review:
```
ACs: X/Y addressed | Forgotten items: N | Unjustified deferrals: N
```
## Part 3: Required Finding Classification
You MUST classify your findings into these lanes:
-**Mainline Gaps**: plan-derived work or AC progress that is missing, incomplete, or regressing
-**Blocking Side Issues**: bugs or implementation issues that block the current mainline objective from succeeding safely
-**Queued Side Issues**: valid non-blocking follow-up issues that should be documented but must NOT take over the next round
This verdict line is mandatory. If you omit it, the Humanize stop hook will block the round and require the review to be rerun.
If Claude mostly worked on queued side issues and failed to advance the mainline, say so explicitly.
## Part 4: {{GOAL_TRACKER_UPDATE_SECTION}}
## Part 5: Output Requirements
- In short, your review comments can include: problems/findings/blockers; claims that don't match reality; implementation plans for deferred work (to be implemented now); implementation plans for unfinished work; goal alignment issues.
- Your output should be structured so Claude can tell which items are mainline gaps, blocking side issues, and queued side issues.
- If after your investigation the actual situation does not match what Claude claims to have completed, or there is pending work to be done, output your review comments to @{{REVIEW_RESULT_FILE}}.
-**CRITICAL**: Only output "COMPLETE" as the last line if ALL tasks from the original plan are FULLY completed with no deferrals
- DEFERRED items are considered INCOMPLETE - do NOT output COMPLETE if any task is deferred
- UNFINISHED items are considered INCOMPLETE - do NOT output COMPLETE if any task is pending
- The ONLY condition for COMPLETE is: all original plan tasks are done, all ACs are met, no deferrals or pending work allowed
- The word COMPLETE on the last line will stop Claude.
> **Note on Deterministic Designs**: If the draft specifies a highly deterministic design with no choices (e.g., "must use JSON format", "must use algorithm X"), then the path boundaries should reflect this narrow constraint. In such cases, upper and lower bounds may converge to the same point, and "Allowed Choices" should explicitly state that the choice is fixed per the draft specification.
## Feasibility Hints and Suggestions
> **Note**: This section is for reference and understanding only. These are conceptual suggestions, not prescriptive requirements.
-<Topic>: Claude vs Codex summary, chosen resolution, and rationale
### Convergence Status
- Final Status: `converged` or `partially_converged`
## Pending User Decisions
- DEC-1: <Decisiontopic>
- Claude Position: <...>
- Codex Position: <...>
- Tradeoff Summary: <...>
- Decision Status: `PENDING` or `<User's final decision>`
## Implementation Notes
### Code Style Requirements
- Implementation code and comments must NOT contain plan-specific terminology such as "AC-", "Milestone", "Step", "Phase", or similar workflow markers
- These terms are for plan documentation only, not for the resulting codebase
- Use descriptive, domain-appropriate naming in code instead
## Output File Convention
This template is used to produce the main output file (e.g., `plan.md`).
### Translated Language Variant
When `alternative_plan_language` resolves to a supported language name through merged config loading, a translated variant of the output file is also written after the main file. Humanize loads config from merged layers in this order: default config, optional user config, then optional project config; `alternative_plan_language` may be set at any of those layers. The variant filename is constructed by inserting `_<code>` (the ISO 639-1 code from the built-in mapping table) immediately before the file extension:
-`plan.md` becomes `plan_<code>.md` (e.g. `plan_zh.md` for Chinese, `plan_ko.md` for Korean)
The translated variant file contains a full translation of the main plan file's current content in the configured language. All identifiers (`AC-*`, task IDs, file paths, API names, command flags) remain unchanged, as they are language-neutral.
When `alternative_plan_language` is empty, absent, set to `"English"`, or set to an unsupported language, no translated variant is written. Humanize does not auto-create `.humanize/config.json` when no project config file is present.
# Build the augmented prompt with web-search instruction
AUGMENTED_PROMPT="You MUST use Google Search to find the most up-to-date and accurate information before answering. Perform thorough web research. Cite sources where possible.
