polyarch/humanize/humanize-refine-plan

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:

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

Usage

# 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