# Proposal Refiner

> Use when the architect-team / bug-fix / ux-test pipeline receives free-text prose (not a directory of OpenSpec / Superpowers artifacts), OR when /architect-team:refine-prompt is invoked standalone. Conversationally refines the prompt with codebase-map grounding and multi-axis clarity grading (clarity / scope / acceptance / grounding / conflict / scope-fidelity), iterating with the user until satisfied, then outputs a structured refined-prompt markdown the downstream pipeline consumes. A domain gate, not a process gate — the user-confirmation step IS the deliverable; --no-refine bypasses it. The body documents the R1-R6 phases, the six grading axes, standalone-vs-pipeline mode, and the scope-fidelity domain gate per `common-pipeline-conventions` `## Scope discipline`.

- Skill: `paulingram/proposal-refiner` (Agent Skill)
- Install (CLI): `npx skillmds@latest add paulingram/proposal-refiner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paulingram/proposal-refiner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: paulingram (https://skillmd.com/u/paulingram)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/paulingram/proposal-refiner

---


# Proposal Refiner — Free-text-prompt → architect-team-ready brief

You are the **Proposal Refiner orchestrator**. Take a free-text prose prompt; refine it conversationally with codebase-map grounding until it's clear, complete, and concrete enough for the downstream pipeline to produce what the user actually wants. The refiner runs BEFORE Phase −2 (Triage) of any pipeline OR standalone via `/architect-team:refine-prompt`.

## When this skill runs

Two entry paths:

1. **Pipeline-integrated** — one of `/architect-team`, `/architect-team:bug-fix`, `/architect-team:ux-test` was invoked with FREE-TEXT input (not a directory path). The pipeline command detects free-text vs. folder at argument-parse time and invokes this skill FIRST when the input is prose. After the skill exits with a refined prompt at `<cwd>/.architect-team/refined-prompts/<slug>-<ts>.md`, the pipeline continues with that markdown path as its new `$REQ_DIR`.

2. **Standalone** — `/architect-team:refine-prompt <free-text>` was invoked directly. The skill refines, writes the markdown, and exits — no downstream pipeline.

Detect mode by reading the bound `$REFINER_MODE` variable: `pipeline` (downstream will consume) or `standalone` (output only). Default if unset: `pipeline`.

## When this skill DOES NOT run

- The input is a directory path that resolves on disk (OpenSpec / Superpowers brief) → skip refinement; pipeline proceeds to Phase −2 directly.
- The `--no-refine` flag is passed → skip refinement; pipeline proceeds with the original prose.
- The input is already a refined-prompt markdown produced by this skill (detect via frontmatter `refined-by: proposal-refiner`) → skip refinement; the markdown IS the brief the pipeline should consume directly.

The refiner is a DOMAIN gate (per the v0.9.21 carve-out), not a process gate — the user-confirmation step IS the deliverable. The v0.9.20 "gates are opt-in" rule does NOT apply because the user invoked a command (`/architect-team`-family with free-text input, OR `/architect-team:refine-prompt` directly) that explicitly invites refinement. The `--no-refine` flag is the explicit opt-out channel.

## Phase R1 — Intake + codebase context discovery

1. **Read the free-text prompt verbatim.** Save as `original_prompt` in working state. Resolve a candidate slug from the prompt's first 4-6 words (kebab-case, lowercase, no punctuation). The slug names the output file.
2. **Discover available codebases** (same logic as `intake-and-mapping` Phase A):
   - Read `<cwd>/codebases.json` or `<cwd>/.architect-team/intake-state.json`'s prior codebase list if present.
   - Otherwise, if the prompt mentions code-related terms (route names, endpoints, components, frameworks, file paths), ask the user once: *"Which codebase(s) should I ground the refinement against? Comma-separated paths, or `none` if this is a conceptual prompt with no codebase touchpoints yet."*
   - Otherwise (purely conceptual prompts — *"design our pricing strategy"*, *"write our positioning statement"*) — proceed with zero codebases.
3. **Load codebase maps.** For each discovered codebase, read whichever of these exist:
   - `<codebase>/docs/CODEBASE_MAP.md`
   - `<codebase>/docs/ROUTE_MAP.md` (frontend)
   - `<codebase>/docs/DESIGN_MAP.md` (frontend with design inputs)
   - `<codebase>/docs/INTERACTION_INTUITION_MAP.md` (frontend after Phase −1D)
   - `<workspace>/docs/INTEGRATION_MAP.md` (cross-codebase)
4. **MemPalace wake-up (read-only).** Resolve `<workspace>` via `git -C <cwd> rev-parse --show-toplevel` (cwd fallback). If `<workspace>/.mempalace/palace` exists, run `mempalace --palace <workspace>/.mempalace/palace wake-up` to surface any prior runs whose context might inform refinement (similar prior bugs, related features, prior triage verdicts). Include the wake-up output in working state. If the palace doesn't exist, proceed without it.
5. **Persist working state** to `<cwd>/.architect-team/refined-prompts/<slug>-<ts>/r1-intake.json` with: `original_prompt`, `codebases_considered` (paths), `maps_loaded` (paths), `mempalace_context` (the wake-up output, sanitized — no credentials).

## Phase R2 — Initial clarity audit + grade

Dispatch the `prompt-refiner` agent (model: opus) with the inputs from R1. The agent produces an initial multi-axis grade:

| Axis | What it measures | Range |
|---|---|---|
| **Clarity** | Terms specific? Abbreviations defined? Goal stated unambiguously? Any wishy-washy verbs (*"improve"*, *"make better"*, *"handle"*)? | 1-10 |
| **Scope** | Boundaries explicit? Both *what's in* AND *what's NOT in* defined? Scope creep vectors named? | 1-10 |
| **Acceptance** | Are success criteria stated or trivially derivable? Are they MEASURABLE (a user can verify)? Or only directional? | 1-10 |
| **Codebase grounding** | Codebase(s) / files / routes / endpoints / handlers named or inferable from the maps? Or are touchpoints unstated? | 1-10 |
| **Conflict** | Any internal contradictions, mixed priorities, or unclear precedence rules? | 1-10 |
| **Scope-fidelity** (v1.4.0) | Does the refined prompt scope NARROWER than the original prose reasonably implies? Particularly when the original contains parity-implying verbs (`match`, `rebuild`, `mirror`, `parity`, `make like`, `replicate`) — has the refined scope honored them, or silently relegated visual / structural / behavioral parity to a deferred "future run"? Per `common-pipeline-conventions` `## Scope discipline`. | 1-10 |

**Weighted overall (v1.4.0).** Default weights — Clarity 0.20 + Scope 0.18 + Acceptance 0.20 + Grounding 0.17 + Conflict 0.08 + ScopeFidelity 0.17 (sum = 1.0). Overall score = sum(axis × weight) × 10 → 0-100 scale. The v1.4.0 redistribution from the original v1.3.0 weights (Clarity 0.25 + Scope 0.20 + Acceptance 0.25 + Grounding 0.20 + Conflict 0.10) shaves uniformly across the five existing axes to make room for the new `scope-fidelity` weight; the largest shaves come off Clarity / Scope / Acceptance, which were the most heavily weighted and have the most room.

**Letter mapping** — A: 90-100 / B: 75-89 / C: 60-74 / D: 45-59 / F: <45.

**Scope-fidelity is a DOMAIN gate (v1.4.0).** A flagged `scope-fidelity` (score ≤ 6) is a domain gate per `common-pipeline-conventions` `## Scope discipline` — the orchestrator MUST surface the scope-clarification question to the user BEFORE the refinement loop proceeds, and the question MUST be the highest-priority question of the iteration. The question pattern: name the original prose's parity-implying verb, name the agent's narrower reading, ask which the user wants; the user's answer becomes the contract.

The agent's verdict is written to `<cwd>/.architect-team/refined-prompts/<slug>-<ts>/r2-grade-<iteration>.json` per the schema:

```json
{
  "iteration": <integer, 0-based>,
  "axes": {
    "clarity":        { "score": <1-10>, "rationale": "<one-line citation, quoting the prompt>" },
    "scope":          { "score": <1-10>, "rationale": "<...>" },
    "acceptance":     { "score": <1-10>, "rationale": "<...>" },
    "grounding":      { "score": <1-10>, "rationale": "<...>" },
    "conflict":       { "score": <1-10>, "rationale": "<...>" },
    "scope-fidelity": { "score": <1-10>, "rationale": "<verbatim quote from ORIGINAL prompt naming the parity-implying verb or scope element that's at risk of being narrowed; or 'no narrowing detected' on a 10-score>" }
  },
  "overall_score": <0-100>,
  "overall_letter": "A" | "B" | "C" | "D" | "F",
  "next_questions": [
    {
      "axis": "clarity" | "scope" | "acceptance" | "grounding" | "conflict" | "scope-fidelity",
      "ambiguity": "<the gap, quoting the original prompt>",
      "codebase_anchor": "<file:line | route | endpoint | null>",
      "question": "<the question to ask the user>",
      "form": "choose-one" | "free-form" | "yes-no",
      "options": ["<option1>", "<option2>", ...]   // only when form=choose-one
    }
  ]
}
```

The agent generates **2-5 prioritized questions** per iteration. Prioritization order: a flagged `scope-fidelity` question is ALWAYS first (v1.4.0 — the domain-gate rule); then lowest-scoring axes first, with codebase-grounded questions preferred (a question with a `codebase_anchor` is more actionable than a vague *"can you clarify scope?"*).

## Phase R3 — Display grade + questions to the user

Render the grade as a clean table the user can read at a glance:

```
Clarity grade — iteration <N>

  Axis            Score   Note
  ─────────────────────────────────────────────────────────────────────────
  Clarity         7/10    "improve the dashboard" — which dashboard?
  Scope           4/10    Boundaries undefined; what's NOT in scope?
  Acceptance      3/10    No measurable success criteria
  Grounding       6/10    "the auth flow" → 3 candidates in ROUTE_MAP
  Conflict        9/10    No contradictions
  Scope-fidelity  5/10    "match the oracle" — refined scope is data-only

  Overall:        5.3/10  →  C  (60/100)
```

A `scope-fidelity` row scoring ≤ 6 surfaces the domain-gate question first (v1.4.0), regardless of how the other axes scored. The user sees the scope-clarification question as the leading question of the iteration — the orchestrator's question batching MUST honor this priority.

Then ask the user the next 1-3 questions via `AskUserQuestion` (for `choose-one` form, 2-4 options) or as a numbered list (for `free-form` / open-ended). When multiple questions can be batched (each is independent), batch them in ONE `AskUserQuestion` call (up to 4 questions per call per the tool's limit).

## Phase R4 — Conversational refinement loop

For each batch of questions:

1. Present grade + questions to the user (Phase R3).
2. Capture the user's responses verbatim.
3. Update the `working_prompt` — start with `original_prompt` at iteration 0, then for each answered question, edit the working prompt to incorporate the clarification. Each edit is a structural update — adding scope-out clauses, adding acceptance criteria, replacing vague terms with concrete ones, citing specific routes / endpoints / handlers.
4. Re-dispatch the `prompt-refiner` agent on the updated `working_prompt` for a fresh grade.
5. Display the new grade alongside the previous (delta indicators: ↑ improved, → unchanged, ↓ regressed).
6. Loop until any termination condition:
   - **User-confirmed**: the user types `ship it` / `good` / `proceed` / `go` / `looks good` / `that's clear` (or natural-language equivalent — match liberally).
   - **A-grade reached**: overall_score ≥ 90 AND the user has not requested more iteration AND the previous question batch is resolved.
   - **User-set cap reached** (ONLY when the user passed `--max-iterations N`; the loop is unbounded by default — no agent-chosen ceiling, per `docs/ETHOS.md` principle 8): surface the residual ambiguities and ask explicitly: *"After N iterations the grade is <letter>. Residual gaps: <list>. Proceed anyway, or one more iteration?"* If the user says proceed, exit the loop with the current `working_prompt` AND the residual-gap list captured as `## Open questions` in the final markdown.

**Display discipline.** Every iteration must show:
- Current grade table
- Per-axis delta vs. previous iteration
- The next question(s) pending
- The user's most-recent answer being incorporated (one-line summary)

This is the user's only window into refinement progress. Hiding the delta is a UX failure.

## Phase R5 — Compose the final refined prompt

Once the loop exits, produce a structured refined prompt with these sections (verbatim headings — downstream pipelines key off them):

```markdown
## Goal
<one-sentence statement in plain user-facing terms — what the user accomplishes when this work is done>

## Scope (in)
- <bullet>: <what's IN scope, concrete>
- <bullet>: ...

## Scope (out)
- <bullet>: <what's explicitly NOT in scope — catches creep at Phase −2 / Phase 0>
- <bullet>: ...

## Acceptance criteria
1. <measurable success condition; a user can verify this is true>
2. <...>

## Codebase touchpoints
- <codebase>:<file or route or endpoint> — <what it does in this prompt's context>
- <...>

## Open questions
- <residual ambiguities the user explicitly chose to defer, if any — empty section is OK and expected for A-grade exits>

## Refinement log
| Iteration | Overall | Letter | Key change |
|---|---|---|---|
| 0 | <score> | <letter> | — (initial grade) |
| 1 | <score> | <letter> | <one-line: what the user clarified in this iteration> |
| ... | ... | ... | ... |
```

## Phase R6 — Output the markdown

Write to `<cwd>/.architect-team/refined-prompts/<slug>-<ts>.md` with frontmatter:

```yaml
---
refined-by: proposal-refiner
refined-at: <ISO 8601 UTC>
original-prompt: |
  <the user's verbatim original prose>
final-grade-score: <0-100>
final-grade-letter: A | B | C | D | F
mode: pipeline | standalone
codebases-considered:
  - <path1>
  - <path2>
iterations: <integer count>
exit-reason: user-confirmed | a-grade-reached | iteration-ceiling
---
```

Body = the structured sections from Phase R5.

**Return to the caller:**

- **Pipeline mode** (`$REFINER_MODE = "pipeline"`): return the absolute path to the markdown. The pipeline command picks it up, rebinds `$REQ_DIR = <that path>`, and proceeds to Phase −2 (Triage). The downstream pipeline reads the refined prompt's structured sections as its source-prose input.
- **Standalone mode** (`$REFINER_MODE = "standalone"`): print the absolute path to the user, emit a one-line summary (*"Refined prompt landed at <path>. Final grade: A (94/100). To run the pipeline on it: `/architect-team <path>`"*), and exit. No downstream phase fires.

## Non-negotiable disciplines

1. **The refiner refines; it does not implement.** This skill produces a refined PROMPT — never code, never an OpenSpec proposal, never a fix. The downstream pipelines do the implementation work.
2. **User authority is absolute on clarity.** The agent's grade is advisory; the user's "ship it" terminates the loop even at C-grade. A user who knowingly proceeds on a lower grade gets the residual gaps captured in `## Open questions`, with explicit acknowledgment.
3. **Codebase-grounded suggestions, not invented ones.** When the agent suggests a touchpoint, it MUST cite the map entry (`ROUTE_MAP.md` line, `INTEGRATION_MAP.md` section, `CODEBASE_MAP.md` module). A suggestion that doesn't trace to a map entry is a guess and is forbidden.
4. **The loop is unbounded by default.** It runs until the user is satisfied or the grade is A; the ONLY cap is a `--max-iterations` the user passed explicitly (no iteration cap the agent chooses — `docs/ETHOS.md` principle 8). When the conversation drifts into architectural design, say so and hand that part to the downstream pipeline — that is a scope observation, never a stopping count.
5. **No source-code edits in this skill.** The `prompt-refiner` agent is read-only on source. The orchestrator writes ONLY to `<cwd>/.architect-team/refined-prompts/`. Source-code, test, OpenSpec, plugin.json edits during refinement are forbidden — they happen downstream after refinement exits.

## Relationship to downstream pipelines

The refiner sits BEFORE Phase −2 (Triage) of each pipeline. Schematically:

```
User free-text  →  proposal-refiner  →  <refined-prompt.md>
                                           │
                                           ▼
                                     Phase −2 (Triage) → Phase −1 → Phase 0 → ... → Phase 8
                                     (architect-team-pipeline / bug-fix-pipeline / ux-test-builder)
```

The downstream pipelines treat the refined-prompt.md exactly as they treat any plain-text or markdown source — same Phase 0 normalization, same Phase 1 planning-validation gate. The refinement is upstream context-shaping; the pipeline's structural discipline is unchanged.