cue-ai 0.9.0 → 0.9.2

package/resources/skills/skills/meta/profile-from-docs/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: profile-from-docs
+description: 'Use when the user says "create a cue profile for X", "wire X into cue", or "build a profile from these docs". Scaffolds an integration profile: profile.yaml, logo, skills, MCPs, and CLI recipes.'
+tags: [meta, cue, profile, scaffolding, mcp, skills]
+---
+
+# Profile From Docs
+
+Turn an upstream product's documentation repo into a complete cue profile:
+the `profile.yaml`, a logo, a set of lint-clean skills, wired MCP servers, and
+CLI recipes. This codifies the clone → map → build → verify loop.
+
+## Use This Skill For
+
+- Standing up a new integration profile (Strapi, Supabase, a new platform)
+  from its official docs
+- Making sure the profile actually loads, lints, and materializes before you
+  hand it over
+
+## Prerequisites
+
+- Run from the `cue` repo root (the one with `profiles/`, `resources/skills/`,
+  `resources/mcps/`)
+- `git` for cloning the upstream docs
+- `bun` to run the cue source (`bun src/index.ts ...`) and the linter
+- Note: `resources/skills` and `resources/mcps` are git submodules; commits
+  land there first, then the main repo bumps the pointers
+
+## Step 1: Opensrc the docs
+
+Clone the upstream docs into `/tmp` (read-only reference, never committed):
+
+```bash
+git clone --depth 1 <docs-repo-url> /tmp/<name>-docs
+```
+
+## Step 2: Map the docs to cue surfaces
+
+Scan for the four things a profile needs. Grep the docs, do not guess.
+
+| cue surface | Look for in the docs |
+|---|---|
+| **MCP servers** | grep the docs for "mcp" / "model context protocol"; capture exact URLs, transport, auth. Prefer official servers over community ones. |
+| **CLI** | the install/scaffold command and the subcommand reference |
+| **Skills** | top-level doc sections (CLI, APIs, plugins, deploy, config), one skill per cohesive area |
+| **Logo** | `find . -iname '*logo*' \( -iname '*.png' -o -iname '*.svg' \)` |
+
+## Step 3: Build the artifacts
+
+### profile.yaml + logo
+
+```bash
+mkdir -p profiles/<name>
+cp /tmp/<name>-docs/path/to/logo.png profiles/<name>/logo.png
+```
+
+Write `profiles/<name>/profile.yaml`: `name`, `icon`, `iconImage: logo.png`,
+`description`, `inherits: core`, a `persona`, `skills.local`, `mcps`, and an
+`env` block for any MCP placeholders. Validate fields against
+`profiles/schema.json`.
+
+### Skills
+
+One skill per area under `resources/skills/skills/<name>/<skill>/SKILL.md`.
+Each must satisfy the linter (see Step 4): `name`, a `description` with a
+trigger phrase, `tags`, a `## Prerequisites` section if it uses a CLI, an
+example, and no em dashes.
+
+### MCP servers
+
+Add each server to `resources/mcps/configs/claude.sanitized.json` under
+`servers`. An unknown id throws `McpNotFound` at materialize time, so the id
+in `profile.yaml` `mcps:` must match the registry key exactly.
+
+```json
+"<id>": { "type": "http", "url": "${SERVICE_URL}/mcp",
+  "headers": { "Authorization": "Bearer ${SERVICE_TOKEN}" } }
+```
+
+`${VAR}` placeholders resolve from the profile's `env:` then the shell.
+Declare every placeholder in `env:` (an empty default is fine) so
+materialization never throws `UnresolvedEnvPlaceholder`.
+
+### CLI recipes
+
+Add install recipes to `resources/cli-recipes.json` (npm / brew / apt / etc.)
+for any CLI the skills invoke.
+
+## Step 4: Verify before claiming done
+
+```bash
+# every skill lints clean (0 errors); --fix auto-resolves em dashes
+bun src/index.ts lint-skill resources/skills/skills/<name>/<skill>/SKILL.md
+
+# profile loads and appears in the picker
+bun src/index.ts list | grep <name>
+
+# both MCPs materialize with env substitution (no throw)
+bun -e 'import {loadProfile} from "./src/lib/profile-loader.ts";
+import {materializeMcp} from "./src/lib/mcp-materializer.ts";
+const p=await loadProfile("<name>");
+console.log(Object.keys((await materializeMcp(p)).claude.mcpServers));'
+```
+
+## Step 5: Commit across the submodules
+
+```bash
+# 1. skills submodule — stage ONLY your paths, not others' in-flight work
+git -C resources/skills add skills/<name>
+git -C resources/skills commit -m "feat(skills): add <name> skills"
+# 2. mcps submodule
+git -C resources/mcps add configs/claude.sanitized.json
+git -C resources/mcps commit -m "feat(mcps): register <name> servers"
+# 3. main repo — profile + recipes + submodule pointer bumps
+git add profiles/<name> resources/cli-recipes.json resources/skills resources/mcps
+git commit -m "feat(profiles): add <name> profile"
+```
+
+## Example
+
+> "opensrc https://github.com/strapi/documentation and build a Strapi profile
+> with skills, MCPs, and CLIs."
+
+Result: `profiles/strapi/` (logo + yaml wiring the `strapi-docs` and
+`strapi-mcp` servers), six skills under `resources/skills/skills/strapi/`,
+two server entries in `claude.sanitized.json`, and `create-strapi` + `strapi`
+recipes, all lint-clean and materialize-verified.
+
+## Rules
+
+- Map from the real docs; never invent MCP URLs, CLI flags, or API shapes.
+- Prefer official MCP servers over community forks.
+- One skill per cohesive area; do not cram CLI + API + deploy into one file.
+- Declare every `${VAR}` in the profile `env:` or materialization throws.
+- Stage only your own paths in the submodules; leave unrelated changes alone.
+- Not done until lint, load, and materialize all pass.
+
+## Next Step
+
+After verifying, feature the profile in `profiles/_featured.yaml`, or run
+`description-optimizer` on any skill whose activation you want to tune.

package/resources/skills/skills/meta/ralph-loop/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: ralph-loop
+description: >-
+  Use when user says "run this in a loop", "work on it overnight", "keep going
+  until done", "ralph loop", "autonomous loop", "make claude work longer", or
+  "run until tests pass". Runs an autonomous Ralph-Wiggum loop — re-feeds one
+  goal prompt to the agent over and over until a stop condition (tests green /
+  PRD done) or a budget/iteration cap, with checkpoints each round. NOT for
+  one-shot tasks or interactive back-and-forth.
+tags: [meta, cue, automation, autonomous, loop]
+category: meta
+version: 1.0.0
+---
+
+# ralph-loop — make the agent work longer (autonomously)
+
+The "Ralph Wiggum" technique (Geoffrey Huntley: *"Ralph is a Bash loop"*): keep
+feeding the agent the **same goal prompt** until the work is actually done. Each
+iteration sees the previous round's file changes + git history, so it grinds
+toward completion. Huntley famously ran a 3-month loop that built a whole
+programming language. The loop is trivial; **the guardrails are the real work.**
+
+## The Iron Law
+
+**No loop without an automated stop condition.** You can't review a 26-hour run
+by hand, so the loop must verify *itself* — typically "tests pass" or a checked
+acceptance command. A loop with no stop check drifts and burns money. If the
+user can't name a verifiable "done", stop and ask for one before looping.
+
+## Two ways to run it
+
+1. **In-session (recommended, safest):** the official Anthropic plugin
+   `ralph-wiggum` — a Stop hook intercepts the agent's exit and re-feeds the
+   prompt. No external script.
+   `/plugin marketplace add anthropics/claude-code` → enable `ralph-wiggum`.
+2. **External loop (this skill's `scripts/loop.sh`):** a guarded `while` loop
+   that re-runs the agent, runs your stop-check after each round, checkpoints to
+   git, and caps iterations. Use when you want it outside a live session.
+
+## Run the included script
+
+```bash
+# Loop until `bun test` passes, max 30 rounds, checkpoint each round:
+scripts/loop.sh --prompt ./GOAL.md --until "bun test" --max 30 --checkpoint
+
+# Fully unattended (skips permission prompts — ONLY in a sandbox/VM/container):
+scripts/loop.sh --prompt ./GOAL.md --until "bun test" --max 30 --yolo
+```
+
+`GOAL.md` states the objective **and** the done-criterion in plain text
+(e.g. "Implement X. You are done when `bun test` is green and `bun run build`
+succeeds."). Stop-check `--until` is the machine-truth that ends the loop.
+
+## Guardrails (do not skip)
+
+- **Stop condition** — `--until "<cmd that exits 0 when done>"`. Required.
+- **Cap iterations** — `--max N` (default 50) so a stuck loop can't spin forever.
+- **Budget** — the Agent SDK exposes `max_budget_usd` / `maxTurns`; for the CLI,
+  the iteration cap is your ceiling. A YC team shipped 6 repos overnight for ~$297 —
+  cost is real.
+- **Sandbox `--yolo`** — unattended mode passes `--dangerously-skip-permissions`,
+  which runs arbitrary commands. Only in a throwaway container/VM/worktree.
+- **Checkpoint** — `--checkpoint` commits after each round so progress is
+  recoverable and you can diff what each iteration did.
+
+## Already in your stack
+
+cue ships a `/loop` skill (interval / self-paced reruns of a prompt or slash
+command) and `codex-fleet` for multi-agent orchestration — you can drive a
+Ralph loop natively without an external repo. This skill's script is the
+zero-dependency fallback.
+
+## Open-source references (verified June 2026, by stars)
+
+| Repo | ⭐ | Note |
+|---|---|---|
+| `anthropics/claude-code` (`ralph-wiggum` plugin) | 129k | Official Stop-hook loop. Start here. |
+| `frankbria/ralph-claude-code` | 9.2k | Loop with intelligent exit detection. |
+| `smtg-ai/claude-squad` | 7.7k | Manage many agents in parallel. |
+| `mikeyobrien/ralph-orchestrator` | 2.9k | Hardened Ralph orchestration. |
+| `michaelshimeles/ralphy` | 2.9k | Bash loop, multi-CLI, runs until PRD complete. |
+
+Source: Huntley's writeups + the official plugin README.

package/resources/skills/skills/meta/ralph-loop/scripts/loop.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# ralph-loop — a guarded "Ralph Wiggum" autonomous loop for Claude Code.
+#
+# Re-feeds one goal prompt to `claude` until a stop-check command succeeds, an
+# iteration cap is hit, or you Ctrl-C. The stop-check is the only source of
+# truth for "done" — keep it honest (tests/build), never a vibe.
+#
+# Usage:
+#   loop.sh --prompt GOAL.md --until "bun test" [--max 50] [--sleep 2]
+#           [--checkpoint] [--yolo] [--agent claude]
+#
+#   --prompt FILE    File whose contents are fed to the agent each round (required).
+#   --until "CMD"    Shell command; loop stops when it exits 0 (required).
+#   --max N          Hard cap on iterations (default 50). Prevents runaway spin.
+#   --sleep S        Seconds between rounds (default 2).
+#   --checkpoint     git add -A && commit after each round (recoverable progress).
+#   --yolo           Pass --dangerously-skip-permissions (UNATTENDED). Sandbox only.
+#   --agent CMD      Agent CLI to invoke (default: claude).
+#
+# Exit: 0 if the stop-check passed; 1 if the iteration cap was reached first.
+set -euo pipefail
+
+PROMPT=""; UNTIL=""; MAX=50; SLEEP=2; CHECKPOINT=0; YOLO=0; AGENT="claude"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --prompt) PROMPT="${2:?}"; shift 2;;
+    --until) UNTIL="${2:?}"; shift 2;;
+    --max) MAX="${2:?}"; shift 2;;
+    --sleep) SLEEP="${2:?}"; shift 2;;
+    --checkpoint) CHECKPOINT=1; shift;;
+    --yolo) YOLO=1; shift;;
+    --agent) AGENT="${2:?}"; shift 2;;
+    -h|--help) sed -n '2,22p' "$0"; exit 0;;
+    *) echo "unknown arg: $1" >&2; exit 2;;
+  esac
+done
+
+[ -n "$PROMPT" ] || { echo "error: --prompt is required" >&2; exit 2; }
+[ -f "$PROMPT" ] || { echo "error: prompt file not found: $PROMPT" >&2; exit 2; }
+[ -n "$UNTIL" ]  || { echo "error: --until <stop-check command> is required (the Iron Law)" >&2; exit 2; }
+command -v "$AGENT" >/dev/null || { echo "error: agent CLI '$AGENT' not on PATH" >&2; exit 2; }
+
+AGENT_FLAGS=(-p)
+if [ "$YOLO" -eq 1 ]; then
+  echo "⚠️  --yolo: running with --dangerously-skip-permissions. Sandbox only." >&2
+  AGENT_FLAGS+=(--dangerously-skip-permissions)
+fi
+
+# Stop-check first: if we're already done, do nothing.
+if eval "$UNTIL" >/dev/null 2>&1; then
+  echo "✓ stop-check already passes — nothing to do."; exit 0
+fi
+
+i=0
+while [ "$i" -lt "$MAX" ]; do
+  i=$((i + 1))
+  echo "── ralph round $i/$MAX ($(date +%H:%M:%S)) ──"
+  # Feed the goal prompt to the agent. Each round sees prior file changes + git.
+  "$AGENT" "${AGENT_FLAGS[@]}" "$(cat "$PROMPT")" || echo "  (agent exited non-zero — continuing)"
+
+  if [ "$CHECKPOINT" -eq 1 ] && git rev-parse --git-dir >/dev/null 2>&1; then
+    git add -A && git commit -q -m "ralph: round $i" --no-verify 2>/dev/null \
+      && echo "  checkpoint: $(git rev-parse --short HEAD)" || echo "  (nothing to checkpoint)"
+  fi
+
+  if eval "$UNTIL" >/dev/null 2>&1; then
+    echo "✓ stop-check passed after $i round(s): $UNTIL"; exit 0
+  fi
+  sleep "$SLEEP"
+done
+
+echo "✗ hit iteration cap ($MAX) without passing stop-check: $UNTIL" >&2
+exit 1

package/resources/skills/skills/meta/skill-simplify/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: skill-simplify
+description: Use when the user says "simplify skill", "optimize skill", "shrink this skill", or "skill-simplify". Shrinks a SKILL.md without losing behavior, verified by a before/after functional count.
+tags: [meta, cue, skills, quality, refactor]
+category: meta
+version: 1.0.0
+requires_mcps: []
+allowed-tools: Bash(Bash:*), Read, Write, Edit, Grep, Glob, AskUserQuestion
+---
+
+# Skill Simplify
+
+Cut a SKILL.md down to size without changing what it does. The safety net is
+a count-based integrity check: every functional element present before the
+edit must still be present after, or the change reverts.
+
+The gate is heuristic, not a parser. Both the before and after inventories are
+extracted by reading and counting, so a mis-count in either phase can pass a
+lost element (false PASS) or revert a safe edit (false FAIL). A PASS means the
+two manual counts agreed, not that a machine proved equivalence. Spot-check the
+diff on a high-stakes skill.
+
+Run three phases in order. Each phase has a detail file you read on demand,
+not up front:
+
+| Phase | Document | Job |
+|-------|----------|-----|
+| 1 | [phases/01-analysis.md](phases/01-analysis.md) | Build the functional inventory, classify every code block, flag format issues |
+| 2 | [phases/02-optimize.md](phases/02-optimize.md) | Delete descriptive content, merge equivalent variants, fix format |
+| 3 | [phases/03-check.md](phases/03-check.md) | Re-extract the inventory, compare counts, PASS / WARN / FAIL, revert on FAIL |
+
+## When to activate
+
+- User says "simplify skill", "optimize skill", "shrink this skill"
+- User says "compress SKILL.md", "make this skill smaller", "skill-simplify"
+- User hands you a bloated SKILL.md and asks to trim it without breaking it
+
+## Input
+
+Resolve the target to an absolute path. A bare directory means the SKILL.md
+inside it.
+
+```bash
+TARGET="$1"
+case "$TARGET" in
+  *.md) FILE="$TARGET" ;;
+  *)    FILE="$TARGET/SKILL.md" ;;
+esac
+test -f "$FILE" || { echo "Target not found: $FILE"; exit 1; }
+wc -l "$FILE"   # original line count, the Phase 3 before/after anchor
+```
+
+Snapshot the original before any edit so Phase 3 can revert:
+
+```bash
+cp "$FILE" "$FILE.simplify.bak"
+```
+
+## The contract
+
+1. **Preserve every functional element.** Logic blocks, routing branches,
+   schemas, agent and skill calls, error handling, input modes, output
+   artifacts, AskUserQuestion blocks stay verbatim.
+2. **Delete only descriptive content.** ASCII art, flowcharts that duplicate a
+   table, "When to use" prose, examples that just repeat logic shown elsewhere,
+   verbose comments.
+3. **Never summarize algorithm logic.** If-else branches, function bodies, and
+   schema fields are copied, not paraphrased.
+4. **Classify every code block** as `functional` or `descriptive`. Only
+   `descriptive` blocks may be removed. When unsure, mark it `functional` and
+   keep it.
+5. **Merge only equivalent variants.** Two templates that differ by one
+   parameter collapse to one template plus a variant comment that names the
+   dropped case.
+6. **Counts are the gate.** Phase 3 re-extracts the same inventory. Critical
+   categories must not decrease, or the edit reverts.
+
+The critical categories, the ones that trigger a FAIL on any decrease:
+
+```
+functionalCodeBlocks  dataStructures  routingBranches  errorHandlers
+conditionalLogic  askUserQuestions  inputModes  outputArtifacts
+skillInvocations
+```
+
+Descriptive decreases are the whole point and pass clean. Merge-aware
+categories (`agentCalls`, total `codeBlocks`) WARN on a decrease so you verify
+the merged version still covers every original case.
+
+## Error handling
+
+| Situation | What to do |
+|-----------|------------|
+| Target file not found | Report the path, stop |
+| Phase 3 FAIL: a critical category dropped | Restore from `.simplify.bak`, report which category and which elements were lost |
+| Phase 3 FAIL: a new format issue appeared | Restore from `.simplify.bak`, report the new issue |
+| Phase 3 WARN: merge-aware drop | Keep the edit, show the merge justification, ask the user to confirm coverage |
+| Phase 3 PASS | Keep the edit, delete the backup, report lines saved |
+
+## Example
+
+Input: "simplify skill resources/skills/skills/meta/foo" (220-line SKILL.md
+with an ASCII flowchart, a "Best Practices" section restating Core Rules, and
+two AskUserQuestion blocks that differ only by header text).
+
+Process:
+- Phase 1 inventory finds 6 functional code blocks, 2 askUserQuestions, 1
+  routing branch, 3 descriptive blocks (the flowchart and two duplicate
+  examples). Format scan finds one nested-backtick issue.
+- Phase 2 deletes the flowchart and the "Best Practices" section, merges the
+  two AskUserQuestion blocks into one with a `// variant: review mode` comment,
+  fixes the nested backticks. File drops to 150 lines.
+- Phase 3 re-extracts: functional blocks still 6, askUserQuestions now 1 but
+  the merge comment names the dropped variant so it WARNs not FAILs, routing
+  branch still 1. Status PASS with one WARN.
+
+Output: "Reduced foo/SKILL.md from 220 to 150 lines (-32%). PASS. 1 WARN: two
+AskUserQuestion blocks merged into one, variant preserved in comment. Verify
+the merged block still asks both headers."
+
+## Rules
+
+- Run the phases in order. Phase 3 is not optional. A simplification you did
+  not verify is a regression you have not found yet.
+- Keep the backup until Phase 3 reports PASS. Revert on FAIL, do not patch.
+- Do not touch function signatures, variable names, or schema field names.
+  Those are functional even inside a block you are compressing.
+- When a decrease is real and not merge-covered, that is a FAIL. Do not argue
+  the count down, restore and report.
+
+## What this skill does NOT do
+
+- Rewrite descriptions for activation (use `meta/description-optimizer`)
+- Score or audit a skill end to end (use `meta/skill-reviewer`)
+- Split one skill into several (that changes behavior, out of scope)
+- Run the skill being simplified

package/resources/skills/skills/meta/skill-simplify/phases/01-analysis.md

@@ -0,0 +1,173 @@
+# Phase 1: Functional analysis
+
+Read the target, build a quantitative functional inventory with code-block
+classification, find redundancy with line ranges, flag format issues, and
+produce an optimization plan. These counts are the baseline Phase 3 verifies
+against, so be exact.
+
+## Objective
+
+- Build the functional inventory with role classification (the Phase 3 anchor).
+- Find redundancy categories with specific line ranges.
+- Detect format issues.
+- Produce an ordered optimization plan with estimated line savings.
+
+## Step 1.1: Read and measure
+
+```bash
+ORIGINAL_LINES=$(wc -l < "$FILE")
+```
+
+Read the whole file into context. You classify and count by reading, not by
+running a parser. The structures below describe what to track; hold them as
+a mental ledger or jot them in scratch notes.
+
+## Step 1.2: Extract the functional inventory
+
+Count and catalog every functional element. Track each category with enough
+location detail to match it again in Phase 3.
+
+```
+inventory = {
+  codeBlocks:        [ { startLine, endLine, language, purpose, role } ],  // role = functional | descriptive
+  agentCalls:        [ { line, agentType, description, mergeGroup? } ],
+  dataStructures:    [ { line, name, type } ],                             // object | array | schema
+  routingBranches:   [ { line, condition, outcomes[] } ],
+  errorHandlers:     [ { line, errorType, resolution } ],
+  conditionalLogic:  [ { line, condition, trueAction, falseAction } ],
+  askUserQuestions:  [ { line, questionCount, headers[], optionType } ],   // static | dynamic
+  inputModes:        [ { line, mode, description } ],
+  outputArtifacts:   [ { line, artifact, format } ],
+  todoWriteBlocks:   [ { line, phaseCount } ],
+  phaseHandoffs:     [ { line, fromPhase, toPhase } ],
+  skillInvocations:  [ { line, skillName, hasExecutionSteps } ],
+  tables:            [ { startLine, endLine, columns } ],
+  schemas:           [ { line, schemaName, fields[] } ],
+  formatIssues:      [ { line, type, description, severity } ],            // error | warning
+  counts:            {}                                                    // computed totals
+}
+```
+
+Extraction cues:
+
+- **Code blocks**: every fenced pair. Record start, end, language, first
+  meaningful line as the purpose.
+- **Agent calls**: `Agent(`, `Task(`, `subagent_type=`, or a Skill tool call
+  spawning a sub-agent.
+- **Data structures**: `const x = {`, `const x = [`, JSON schema objects.
+- **Routing branches**: `if` / `else`, `switch` / `case`, meaningful ternaries.
+- **Error handlers**: `catch`, error-table rows (`| Error |`), fallback blocks.
+- **AskUserQuestion**: `AskUserQuestion(` blocks, record the questions array
+  length and the option headers.
+- **Input modes**: `Mode 1/2/3`, `--flag`, argument parsing.
+- **Output artifacts**: `Write(`, `Output:`, file paths in comments.
+- **Phase handoffs**: `Read("phases/`, `Skill(`, "proceed to next phase".
+- **Skill invocations**: `Skill(` or a named `/skill` call with its steps.
+- **Tables**: markdown `| header |` blocks.
+- **Schemas**: named JSON structure definitions and their fields.
+
+### Step 1.2.1: Classify each code block
+
+| Role | Criteria | Examples |
+|------|----------|----------|
+| `functional` | Algorithm logic, routing, conditionals, agent calls, schemas, data processing, AskUserQuestion, Skill, Read, Write, Bash | `if (...)`, `Agent({...})`, `const schema = {...}` |
+| `descriptive` | ASCII art, usage examples, display templates, good vs bad comparisons, folder trees | box-drawing chars, `# Example usage`, a bad / good pair, `dir/file.ts` trees |
+
+Rules:
+
+- Contains any of `Agent(`, `Bash(`, `AskUserQuestion(`, `if (`, `switch`,
+  `Skill(`, `Write(`, `Read(`, `TodoWrite(` then it is `functional`.
+- A `bash` block that is only example invocations, no logic, is `descriptive`.
+- A block with no language tag holding only box-drawing characters is
+  `descriptive`.
+- A block under an "Example" heading is `descriptive`.
+- Default to `functional`. Conservative wins, a kept block costs lines, a
+  dropped functional block costs behavior.
+
+### Step 1.2.2: Validate format
+
+Scan the `functional` blocks only:
+
+| Check | Detection | Severity |
+|-------|-----------|----------|
+| Nested backticks | A backtick template literal inside a fenced code block | warning |
+| Unclosed brackets | Unmatched `{`, `(`, `[` in a block | error |
+| Undefined references | `${var}` never declared in this or a prior block | warning |
+| Inconsistent indentation | Mixed tabs and spaces, or jumpy nesting | warning |
+| Dead code | Commented-out blocks spanning 5+ lines | warning |
+| Missing output | A function-like block with no return, Write, or log | warning |
+
+### Step 1.2.3: Compute totals
+
+Total every category, plus the two derived code-block splits:
+
+```
+counts = {
+  codeBlocks, functionalCodeBlocks, descriptiveCodeBlocks,
+  agentCalls, dataStructures, routingBranches, errorHandlers,
+  conditionalLogic, askUserQuestions, inputModes, outputArtifacts,
+  todoWriteBlocks, phaseHandoffs, skillInvocations,
+  tables, schemas, formatIssues
+}
+```
+
+`functionalCodeBlocks` and `descriptiveCodeBlocks` come from the role split in
+1.2.1. These are the numbers Phase 3 reads.
+
+## Step 1.3: Find redundancy
+
+Record line ranges for each, so Phase 2 edits surgically.
+
+**Deletable** (remove entirely, zero functional loss):
+
+| Pattern | Detection |
+|---------|-----------|
+| Duplicate Overview | `## Overview` restating the frontmatter description |
+| ASCII flowchart | A flowchart duplicating a phase table or structure |
+| "When to use" section | Usage prose not needed to execute |
+| Best Practices section | Advice that duplicates Core Rules |
+| Duplicate examples | Examples repeating logic shown elsewhere |
+| Folder-tree duplicate | An ASCII tree repeating an Output Artifacts table |
+| "Next Phase" prose | Phase glue when TodoWrite or a table already handles flow |
+| Descriptive code blocks | Blocks classed `descriptive` covered by nearby prose or tables |
+
+**Simplifiable** (compress, keep meaning):
+
+| Pattern | Strategy |
+|---------|----------|
+| Verbose comments | Reduce to one line, keep only non-obvious notes |
+| Multi-line logging | Collapse to a single template line |
+| Wordy intros | Drop "In this phase we will..." preambles |
+| Prompt bloat | Trim agent or exploration prompts to the essential instruction |
+| Display-format blocks | Convert a block that only defines output shape to a prose sentence |
+
+**Mergeable** (combine related structures):
+
+| Pattern | Strategy |
+|---------|----------|
+| Similar AskUserQuestion blocks | One shared block with a mode parameter |
+| Repeated Option routing | One dispatch |
+| Sequential single-line commands | One code block |
+| Repeated TodoWrite blocks | Template once, the rest as one-line deltas |
+| Duplicate error tables | One table |
+| Equivalent template variants | One template plus a variant comment naming the dropped case |
+| Multiple output-artifact tables | One combined table with a phase column |
+
+**Format fixes**:
+
+| Pattern | Fix |
+|---------|-----|
+| Nested backtick literals | Convert the block to prose, or use a four-backtick fence |
+| Hardcoded option lists | Add a comment: generate dynamically from the named source |
+| Handoff without steps | Add concrete steps referencing the target command's real interface |
+| Unclosed brackets | Match the brackets |
+
+## Step 1.4: Build the plan
+
+Order operations delete then merge then simplify then format. Delete is
+safest and highest impact, format is last so it sees the final structure.
+
+Report a short summary: category counts, estimated reduction percentage, and
+the sections you will NOT touch (the functional core). Carry forward
+`analysisResult = { inventory, redundancyMap, plan, originalContent,
+originalLines }` for the next phases.