/refine-plan

description: "Refine an annotated implementation plan and generate a QA ledger"
argument-hint: "--input <path/to/annotated-plan.md> [--output <path/to/refined-plan.md>] [--qa-dir <path/to/qa-dir>] [--alt-language <language-or-code>] [--discussion|--direct]"
allowed-tools:
  - "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/validate-refine-plan-io.sh:*)"
  - "Read"
  - "Glob"
  - "Grep"
  - "Write"
  - "Edit"
  - "AskUserQuestion"
hide-from-slash-command-tool: "true"

Refine Annotated Plan

Read and execute below with ultrathink.

Hard Constraint: Planning-Only Refinement

This command MUST ONLY refine plan artifacts. It MUST NOT implement repository code, modify source files unrelated to the plan outputs, start RLCR automatically, or create a new plan schema.

Permitted writes are limited to:

• The refined plan output file (`--output`, or `--input` in in-place mode)
• The QA document under `--qa-dir`
• Optional translated language variants for the refined plan and QA document

The refined plan MUST reuse the existing `gen-plan` schema. Do not invent new top-level sections. Keep required sections intact, preserve optional sections when present, and preserve any `--- Original Design Draft Start ---` appendix or other non-comment content unless a comment explicitly requires a plan-level change there.

Workflow Overview

> **Sequential Execution Constraint**: Execute the phases strictly in order. Do NOT parallelize work across phases. Finish each phase before moving to the next one.

1. **Execution Mode Setup**: Parse CLI arguments and derive output paths 2. **Load Project Config**: Resolve `alternative_plan_language` and mode defaults using `config-loader.sh` semantics 3. **IO Validation**: Run `validate-refine-plan-io.sh` 4. **Comment Extraction**: Scan the annotated plan and extract valid comment blocks (`CMT:`/`ENDCMT`, `<cmt>`/`</cmt>`, `<comment>`/`</comment>`) 5. **Comment Classification**: Classify each extracted comment for downstream handling 6. **Comment Processing**: Answer questions, apply requested plan edits, and perform targeted research 7. **Plan Refinement**: Produce the comment-free refined plan while preserving the `gen-plan` structure 8. **QA Generation**: Populate the QA template with the comment ledger and outcomes 9. **Atomic Write**: Commit the refined plan, QA document, and optional variants as one transaction

---

Phase 0: Execution Mode Setup

Parse `$ARGUMENTS` and set the following variables:

• `INPUT_FILE` from `--input` (required)
• `OUTPUT_FILE` from `--output`
• `QA_DIR` from `--qa-dir`
• `CLI_ALT_LANGUAGE_RAW` from `--alt-language`
• `REFINE_PLAN_MODE_DISCUSSION=true` if `--discussion` is present
• `REFINE_PLAN_MODE_DIRECT=true` if `--direct` is present

Argument rules:

1. `--input <path>` is required. 2. `--output <path>` is optional. If omitted, set `OUTPUT_FILE=INPUT_FILE` for in-place mode. 3. `--qa-dir <path>` is optional. If omitted, set `QA_DIR=.humanize/plan_qa`. 4. `--alt-language <language-or-code>` is optional. If present without a value, report `Invalid arguments: --alt-language requires a value` and stop. 5. `--discussion` and `--direct` are mutually exclusive. If both are present, report `Cannot use --discussion and --direct together` and stop.

Derived paths:

1. Compute `IN_PLACE_MODE=true` when `OUTPUT_FILE` equals `INPUT_FILE`; otherwise `false`. 2. Compute `QA_FILE` from the input basename, not the output basename:

• `plan.md` becomes `<QA_DIR>/plan-qa.md`
• `docs/my-plan.md` becomes `<QA_DIR>/my-plan-qa.md`
• `plan` becomes `<QA_DIR>/plan-qa.md`

3. Keep `--alt-language` out of the validator invocation because `validate-refine-plan-io.sh` does not accept it. Pass only:

• `--input`
• `--output` when provided
• `--qa-dir` when provided
• `--discussion` or `--direct` when provided

Scope rules for v1:

• Do not introduce `--language` or `--qa-output`
• Do not add new config keys
• Do not auto-start RLCR after refinement

---

Phase 0.5: Load Project Config

Resolve configuration by following the same precedence and merge semantics defined in `${CLAUDE_PLUGIN_ROOT}/scripts/lib/config-loader.sh`. Reuse that behavior; do not invent a separate refine-plan config model.

Config Merge Semantics

Use the same layer order as `load_merged_config`:

1. Required default config: `${CLAUDE_PLUGIN_ROOT}/config/default_config.json` 2. Optional user config: `${XDG_CONFIG_HOME:-$HOME/.config}/humanize/config.json` 3. Optional project config: `${HUMANIZE_CONFIG:-$PROJECT_ROOT/.humanize/config.json}`

Later layers override earlier layers. Malformed optional JSON objects are treated as warnings and ignored. A malformed required default config is a fatal configuration error.

Values to Extract

Read the merged config and resolve:

• `CONFIG_ALT_LANGUAGE_RAW` from `alternative_plan_language`
• `CONFIG_GEN_PLAN_MODE_RAW` from `gen_plan_mode`

Mode Resolution

Resolve `REFINE_PLAN_MODE` with this priority:

1. CLI `--discussion` => `discussion` 2. CLI `--direct` => `direct` 3. Valid config value `gen_plan_mode` (`discussion` or `direct`, case-insensitive) 4. Default => `discussion`

If `gen_plan_mode` is present but invalid, log a warning and fall back to the next rule.

Alternative Language Resolution

Resolve the variant language with this priority:

1. CLI `--alt-language` 2. Config `alternative_plan_language` 3. No variant

Normalize the value case-insensitively using this mapping table:

| Language | Code | 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` |

Normalization rules:

1. Trim leading and trailing whitespace before matching. 2. Accept either the full language name or the ISO code from the table. 3. Treat `English` / `en` as a no-op: no