// Refine an annotated implementation plan into a comment-free plan and a QA ledger while preserving the gen-plan schema.
Consult Codex as an independent expert. Sends a question or task to codex exec and returns the response.
Start RLCR (Ralph-Loop with Codex Review) on Codex using the native Stop hook.
Iterative development with AI review. Provides RLCR (Ralph-Loop with Codex Review) for implementation planning and code review loops.
Consult Gemini as an independent expert with deep web research. Sends a question or task to Gemini CLI and returns a research-backed response.
Generate a structured implementation plan from a draft document. Validates input, checks relevance, analyzes for issues, and generates a complete plan.md with acceptance criteria.
| name | humanize-refine-plan |
| description | Refine an annotated implementation plan into a comment-free plan and a QA ledger while preserving the gen-plan schema. |
| type | flow |
| user-invocable | false |
Refines an annotated plan that contains CMT: / ENDCMT blocks into a comment-free plan plus a QA ledger, while preserving the gen-plan structure and convergence state.
The installer hydrates this skill with an absolute runtime root path:
{{HUMANIZE_RUNTIME_ROOT}}
flowchart TD
BEGIN([BEGIN]) --> SETUP[Parse arguments and derive paths<br/>Resolve mode, output path, QA path, alt-language]
SETUP --> LOAD_CFG[Load merged config<br/>Reuse humanize config precedence and defaults]
LOAD_CFG --> VALIDATE[Validate IO<br/>Run: {{HUMANIZE_RUNTIME_ROOT}}/scripts/validate-refine-plan-io.sh --input <annotated-plan> [--output ...] [--qa-dir ...] [--discussion|--direct]]
VALIDATE --> VALID_OK{Validation passed?}
VALID_OK -->|No| REPORT_VALIDATION[Report validation error<br/>Stop]
REPORT_VALIDATION --> END_FAIL([END])
VALID_OK --> EXTRACT[Read input plan and extract valid<br/>CMT:/ENDCMT blocks with a stateful scanner]
EXTRACT --> PARSE_OK{Parse succeeded?}
PARSE_OK -->|No| REPORT_PARSE[Report parse error with<br/>line, column, heading, context<br/>Stop]
REPORT_PARSE --> END_FAIL
PARSE_OK --> CLASSIFY[Classify comments:<br/>question, change_request, research_request]
CLASSIFY --> AMBIG{Ambiguous comments?}
AMBIG -->|Yes, discussion mode| ASK_USER[Ask the minimum user question<br/>needed to continue]
ASK_USER --> PROCESS
AMBIG -->|No| PROCESS[Process comments in order:<br/>answer, refine plan, or do targeted repo research]
PROCESS --> REFINE[Generate refined plan text<br/>Keep required gen-plan sections intact]
REFINE --> PLAN_CHECK{Plan still valid?<br/>No CMT markers, references consistent,<br/>routing tags valid}
PLAN_CHECK -->|No, fixable| FIX[Repair internal inconsistencies]
FIX --> PLAN_CHECK
PLAN_CHECK -->|No, blocking| REPORT_BLOCK[Report blocking inconsistency<br/>Stop]
REPORT_BLOCK --> END_FAIL
PLAN_CHECK -->|Yes| QA[Populate QA document from<br/>{{HUMANIZE_RUNTIME_ROOT}}/prompt-template/plan/refine-plan-qa-template.md]
QA --> ALT_LANG{Generate translated variants?}
ALT_LANG -->|Yes| VARIANTS[Translate refined plan and QA<br/>Keep identifiers unchanged]
ALT_LANG -->|No| ATOMIC
VARIANTS --> ATOMIC[Write refined plan, QA, and variants<br/>atomically via temp files]
ATOMIC --> REPORT_SUCCESS[Report success:<br/>paths, counts, mode, convergence status]
REPORT_SUCCESS --> END_SUCCESS([END])
Required Arguments:
--input <path/to/annotated-plan.md> - Input plan that already follows the gen-plan schema and contains at least one CMT: / ENDCMT blockOptional Arguments:
--output <path/to/refined-plan.md> - Output path for the refined plan; defaults to in-place mode (--input)--qa-dir <path/to/qa-dir> - Directory for the generated QA ledger; defaults to .humanize/plan_qa--alt-language <language-or-code> - Optional translated output language for plan and QA variants--discussion - Ask the user to resolve ambiguous classifications or language decisions--direct - Resolve ambiguity with the smallest safe assumption and record it in QAArgument Rules:
--discussion and --direct are mutually exclusive--alt-language, so do not pass that flag to validate-refine-plan-io.sh--output is omitted, refine the plan in place and still write the QA document separatelyThe refinement flow must:
gen-plan schema instead of inventing new top-level sectionsCMT: / ENDCMT blocks from the final plan## Goal Description## Acceptance Criteria## Path Boundaries## Feasibility Hints and Suggestions## Dependencies and Sequence## Task Breakdown## Claude-Codex Deliberation## Pending User Decisions## Implementation Notescoding or analyzeEach extracted raw comment block receives one dominant classification:
questionchange_requestresearch_requestThe flow produces:
CMT-N--alt-language supports these normalized values:
| Language | Code | Variant Suffix |
|---|---|---|
| Chinese | zh | _zh |
| Korean | ko | _ko |
| Japanese | ja | _ja |
| Spanish | es | _es |
| French | fr | _fr |
| German | de | _de |
| Portuguese | pt | _pt |
| Russian | ru | _ru |
| Arabic | ar | _ar |
Rules:
English / en as a no-op| Exit Code | Meaning |
|---|---|
| 0 | Success - continue |
| 1 | Input file not found |
| 2 | Input file is empty |
| 3 | Input file has no CMT: blocks |
| 4 | Input file is missing required gen-plan sections |
| 5 | Output directory does not exist or is not writable |
| 6 | QA directory is not writable |
| 7 | Invalid arguments |
# Start the flow
/flow:humanize-refine-plan
# The flow will ask for:
# - Input annotated plan path
# - Optional output refined plan path
# - Optional QA directory
# - Optional execution mode and alternate language
Or with the skill only (no auto-execution):
/skill:humanize-refine-plan