Refine

Content Refiner

Iteratively improve any text artifact through multi-phase review.

Design Principle

In-place enhancement. Keep format, structure, and author voice intact. Fix content, not layout.

Phases

0. Content-Type Resolution — detect type, load base + type criteria
1. Self-Review Loop — find issues -> fix -> re-check (max 5 iterations)
2. Codex Cross-Validation — find what Claude missed
3. User Resolution — resolve ambiguities & TODOs via AskUserQuestion
4. Final Validation — re-scan for regressions
5. Report — summarize changes

Parameters

Detect from user's request:

Issue Categories

See content-types/_base.md for universal issue types and content-types/{type}.md for type-specific issues. The key distinction: auto-fixable issues (fix is unambiguous) vs requires user input (NEVER guess, NEVER fabricate).

Critical Rules

NEVER Fabricate Content

RED FLAG: You are about to write specific content the user never provided.

STOP. ASK THE USER.

Examples of fabrication:
- Replacing "configure appropriately" with specific config steps you invented
- Replacing a TODO with a decision you made
- Adding file paths, branch names, or commands not in the original file
- Converting a vague instruction into a specific one using your assumptions

The user's file has vague content for a reason — they haven't decided yet,
or the answer depends on context you don't have. ASK, don't guess.

NEVER Skip User Consultation for Ambiguous Issues

Reformatting a TODO (e.g., TODO: X -> > **Open question:** X) is NOT resolving it. The user must decide:

• What value/content to use, OR
• Explicitly keep it as-is (deferred), OR
• Remove it entirely

Always Re-verify After Fixes

A single pass misses issues introduced by fixes. Always re-scan after applying changes.

Workflow

Phase 0: Content-Type Resolution

1. Detect content_type:
   a. User explicit (/refine plan, /refine code, /refine markdown, /refine config)
      -> use that content type
   b. File extension + heuristics:
      - .md -> read file, check for 3+ <task> tags at line start outside code blocks
        -> yes: "plan"
        -> no: "markdown"
      - .ts/.js/.tsx/.jsx/.cs/.py/.go/.rs/.java/.rb/.swift/.kt -> "code"
      - .yaml/.yml/.json/.toml/.ini/.env -> "config"
      - else -> "base-only"

2. Resolve criteria file paths via Glob:
   Glob(pattern="content-types/_base.md", path=<skill directory>)
   Glob(pattern="content-types/{detected_type}.md", path=<skill directory>)

3. Read base_criteria (always):
   Read(file_path=<resolved _base.md path>)

4. Read type_criteria (if not base-only):
   Read(file_path=<resolved {type}.md path>)

5. Store: content_type, base_criteria, type_criteria for use in all subsequent phases

Phase 1: Self-Review Loop

max_iterations = 5
changes = []

for iteration in 1..max_iterations:
    1. Spawn issue-finder agent:
       Task(subagent_type="general-purpose", prompt=<issue-finder prompt
         + file_path
         + content_type
         + mode
         + base_criteria
         + type_criteria>)

    2. Parse response -> auto_fixable_issues, user_issues

    3. If no auto_fixable issues with severity critical or major:
       Fix remaining minor auto-fixable issues
       Store user_issues for Phase 3
       -> Exit Phase 1

    4. For each auto_fixable issue (critical first):
       Skip if already attempted (track by type+location+quote hash)
       Spawn issue-fixer agent to apply fix
       Record in changes[]

    5. Continue loop (re-scan will catch regressions)

Report: "Phase 1: Fixed N issues in M iterations"

Phase 2: Codex Cross-Validation

Setup:

Resolve CODEX_BRIDGE path using the Glob tool (NOT bash — Bash(node:*) restriction blocks ls):

Glob(pattern="**/saurun/*/skills/codex-bridge/codex-bridge.mjs", path="~/.claude/plugins/cache/saurun-marketplace")
-> Use the LAST match (highest version number)
-> Store as CODEX_BRIDGE variable for subsequent node commands

CODEX_TIMEOUT=1200000  # 20 min — MANDATORY, do not shorten

Codex is required. Always attempt Phase 2. If Codex is unavailable (not installed, auth failure, timeout), log a warning and proceed to Phase 3, but flag this prominently in the report. Do NOT skip Phase 2 by choice.

for iteration in 1..5:
    1. Call Codex via codex-bridge with review prompt (see below)
       CRITICAL: Always pass --working-dir and --timeout 1200000

    2. Parse JSON response, validate schema (see content-types/_base.md for valid types)
       - Missing required fields -> skip issue
       - Unknown type -> treat as non-auto-fixable
       - Missing suggestions array -> normalize

    3. For each Codex finding:
       Spawn codex-validator agent -> VALID or INVALID
       If INVALID -> log rejection, skip

    4. If no valid issues -> exit Phase 2

    5. For valid issues:
       Auto-fixable -> spawn issue-fixer, record change
       Needs user -> add to user_issues for Phase 3

Report: "Phase 2: Fixed N issues, deferred M to user"

Codex prompt assembly:

Assemble the prompt from base_criteria and type_criteria Codex sections. Embed the full file content directly in the prompt. The codex-bridge delivers all prompts via stdin (no CLI arg limit, no file relay), so Codex receives the complete content without truncation.

node "$CODEX_BRIDGE" --timeout 1200000 "Review this file for issues that may have been missed.

CONTENT TYPE: [content_type]
MODE: [mode]

LOOK FOR:
{items from base_criteria ## Codex Prompt section}
{items from type_criteria ## Codex Prompt Extension section, numbered continuing from base}

DO NOT FLAG:
{exclusions from base_criteria ## Codex Prompt section}

Return JSON array:
[{
  \"issue\": \"description\",
  \"type\": \"vague_instruction|inconsistent_terminology|broken_reference|redundant_content|formatting_inconsistency|missing_definition|contradiction|unresolved_todo|ambiguous_scope|missing_context|trailing_whitespace|incomplete_list|inconsistent_casing|{type-specific types}\",
  \"severity\": \"critical|major|minor\",
  \"location\": \"line number or section\",
  \"quote\": \"the problematic text\",
  \"auto_fixable\": true|false,
  \"suggestions\": [\"fix options\"]
}]

If no issues: []

===== CONTENT =====
[FULL FILE CONTENT]
===== END CONTENT =====
" --working-dir "$PROJECT_PATH"

Debugging: codex-bridge logs to stderr: prompt size, delivery method, token usage, and any truncation warnings. Check stderr output if findings seem wrong.

Codex-fix mode (when codex-fix parameter detected): Add --full-auto flag. Codex edits directly. Validate fixes with codex-validator. Revert if invalid.

Phase 3: User Resolution

Only issues where auto_fixable == false reach this phase.

CRITICAL: Use the AskUserQuestion TOOL for each issue, one at a time. Do NOT list questions as plain text. Each issue gets its own AskUserQuestion call so the user gets interactive multiple-choice prompts.

If no user_issues -> skip to validation

For each issue (sorted by severity):
    Call AskUserQuestion tool with issue-type-specific options:

    vague_instruction:
      "This is vague: '[quote]'. What should it specify?"
      Options: [suggestion1, suggestion2, "Keep as-is", "Remove"]

    ambiguous_scope:
      "'[quote]' could mean different things. Which interpretation?"
      Options: [interp_a, interp_b, "Both (clarify)", "Keep ambiguous"]

    unresolved_todo:
      "Found unresolved: '[quote]'"
      Options: [suggestion, "Remove entirely", "Keep (resolve later)"]

    inconsistent_terminology:
      "Mixed terms: [term1] (Nx), [term2] (Nx). Standardize to which?"
      Options: ["Use term1", "Use term2", "Keep as-is (different meanings)"]

    contradiction:
      "'[quote1]' conflicts with '[quote2]'"
      Options: ["Keep first", "Keep second", "Rewrite to reconcile", "Keep both"]

    missing_definition / missing_context:
      "'[quote]' is used but never defined/assumes knowledge not provided"
      Options: [suggestion, "Link to docs", "Remove", "Keep as-is"]

    broken_reference (unresolvable):
      "'[quote]' points to non-existent target"
      Options: [suggested_target, "Remove reference", "Keep (fix later)"]

    missing_verification:
      "Task has no verification step: '[quote]'"
      Options: ["Add verification (describe)", "Mark as self-verifying", "Keep (resolve later)"]

    missing_done_criteria:
      "Task has no done criteria: '[quote]'"
      Options: ["Add done criteria (describe)", "Keep (resolve later)"]

    vague_action:
      "Action is too vague to execute: '[quote]'"
      Options: [suggestion1, suggestion2, "Keep as-is", "Remove"]

    type_mismatch:
      "Value type seems wrong: '[quote]'. Expected [expected_type]."
      Options: ["Change to [expected_type]", "Keep current type", "Remove field"]

    orphan_heading:
      "Heading has no content: '[quote]'"
      Options: ["Add content (describe)", "Remove heading", "Keep as placeholder"]

    stale_comment:
      "Comment may not match code: '[quote]'"
      Options: ["Update comment", "Remove comment", "Keep as-is"]

    undefined_dependency:
      "Task depends on undefined resource: '[quote]'"
      Options: ["Define dependency", "Remove reference", "Keep (resolve later)"]

    missing_files_list:
      "Task modifies files but doesn't list them: '[quote]'"
      Options: ["Add file list (describe)", "Keep (resolve later)"]

    unmeasurable_success:
      "Success criteria can't be objectively measured: '[quote]'"
      Options: [suggestion, "Rewrite criteria (describe)", "Keep as-is"]

    missing_type:
      "Missing type annotation: '[quote]'"
      Options: ["Add type (describe)", "Mark as intentionally untyped", "Keep as-is"]

    missing_required_field:
      "Required field is missing: '[quote]'"
      Options: ["Add field with value (describe)", "Remove requirement", "Keep (resolve later)"]

    unused_variable:
      "Variable defined but never referenced: '[quote]'"
      Options: ["Remove variable", "Keep (used elsewhere)", "Keep as-is"]

    no_default_value:
      "Optional field has no default: '[quote]'"
      Options: ["Add default (describe)", "Keep without default"]

    magic_number:
      "Unexplained numeric literal: '[quote]'"
      Options: ["Extract to named constant (describe name)", "Add inline comment", "Keep as-is"]

    Apply user's choice via issue-fixer agent
    Record in changes[]

Report: "Phase 3: Resolved N ambiguities"

Final Validation

1. Run issue-finder one last time (conservative mode)
2. Filter out pre-existing issues -> find genuinely NEW issues from our fixes
3. If new issues -> warn user with list + likely cause
4. If clean -> report "Validation passed"

Report

Print summary:

File: [name]  Content-Type: [content_type]  Mode: [mode]
Phase 1: [N] fixed in [M] iterations
Phase 2: [N] fixed, [M] deferred  [or "Skipped (Codex unavailable)"]
Phase 3: [N] resolved by user
Validation: Passed | [N] regressions found
Total: [N] issues fixed (Claude: X, Codex: Y, User: Z)

Include abbreviated change log: [phase-iteration-change#] type @ location: before -> after

See references/change-log-format.md for full change entry schema and in-memory structure.

Sub-Agents

Spawn each via Task(subagent_type="general-purpose") with the agent's prompt + input parameters.

Red Flags — STOP and Re-read This Skill

• You're about to replace vague content with specifics YOU made up
• You converted a TODO to a different format without asking the user
• You're doing a single pass without re-scanning
• You skipped Phase 2 because "Phase 1 was thorough enough"
• You're not tracking changes
• You resolved an ambiguity without AskUserQuestion
• You listed questions as plain text instead of calling AskUserQuestion tool

All of these mean: you're violating the skill. Re-read and comply.

Common Rationalizations