/humanize-refine-plan

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

Humanize Refine Plan

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 &lt;annotated-plan&gt; [--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])

Input Requirements

**Required Arguments:**

• `--input <path/to/annotated-plan.md>` - Input plan that already follows the `gen-plan` schema and contains at least one `CMT:` / `ENDCMT` block

**Optional 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 QA

**Argument Rules:**

• `--discussion` and `--direct` are mutually exclusive
• The validator does not accept `--alt-language`, so do not pass that flag to `validate-refine-plan-io.sh`
• If `--output` is omitted, refine the plan in place and still write the QA document separately

Workflow Guarantees

The refinement flow must:

• Preserve the `gen-plan` schema instead of inventing new top-level sections
• Remove all resolved `CMT:` / `ENDCMT` blocks from the final plan
• Keep required sections intact:
• `## Goal Description`
• `## Acceptance Criteria`
• `## Path Boundaries`
• `## Feasibility Hints and Suggestions`
• `## Dependencies and Sequence`
• `## Task Breakdown`
• `## Claude-Codex Deliberation`
• `## Pending User Decisions`
• `## Implementation Notes`
• Preserve optional sections when present, including the original design draft appendix
• Keep task routing tags restricted to `coding` or `analyze`
• Generate a QA ledger from the shipped QA template
• Write the refined plan, QA file, and any language variants atomically

Classification And Output

Each extracted raw comment block receives one dominant classification:

• `question`
• `change_request`
• `research_request`

The flow produces:

• A refined plan with comment blocks removed and approved refinements applied
• A QA ledger that records:
• one row per raw `CMT-N`
• classification and disposition
• answers to questions
• research findings
• applied plan changes
• remaining decisions
• refinement metadata and convergence status

Supported Alternate Languages

`--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:

• Accept either the language name or ISO code
• Treat `English` / `en` as a no-op
• Keep identifiers unchanged in translated variants
• If the alternate language matches the main plan language, skip variant generation

Validation Exit Codes

| 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 |

Usage

# Start the