# Pilot Support Rollup

Shell examples run from the target project root. For `scripts/forgeflow/` commands, use the helper path from your ForgeFlow checkout, or replace that prefix with `"${CODEX_HOME:-$HOME/.codex}/forgeflow/scripts/forgeflow/"` for Codex and `"$HOME/.claude/forgeflow/scripts/forgeflow/"` for Claude Code. Run JavaScript helpers with `node` and shell helpers with `bash`. Replace `<project>` with the actual project folder name before running a placeholder example.

Use this after two or more maintainer pilots to find repeated support blockers. Keep raw pilot notes local and roll up only categories, counts, and sanitized observations.

## Inputs

Use local notes from:

- [Pilot Evidence Log](Pilot-Evidence-Log.md)
- [Support Triage](Support-Triage.md)
- [First-Run Friction](First-Run-Friction.md)
- [Friction To Fix](Friction-To-Fix.md)

Do not copy raw `.forgeflow/` artifacts, full settings files, source snippets, or private branch names into the rollup.

Generate a local rollup from pilot evidence notes:

```bash
scripts/forgeflow/rollup-pilot-evidence.js \
  --out ".forgeflow/$(basename "$PWD")/pilot-evidence-rollup.md"
```

For machine-readable output:

```bash
scripts/forgeflow/rollup-pilot-evidence.js --json
```

## Rollup Template

```yaml
pilot_count:
runtimes:
project_types:
blocked_first_review_count:
repeat_issue_count:
support_categories:
  install:
  health:
  settings:
  template-installer:
  codex-discovery:
  agent-routing:
  context-budget:
  review-quality:
  privacy:
  docs:
top_blockers:
fixed_this_round:
next_fix_layer:
owner:
```

## Category Rules

Use the first layer that could have prevented the problem:

| Category | Use When |
|---|---|
| `install` | managed files are missing, corrupt, or not executable |
| `health` | health output is wrong, unclear, or missing a real failure |
| `settings` | hook or statusline wiring is confusing or stale |
| `template-installer` | Codex or Claude template copy behavior is unclear |
| `codex-discovery` | files exist but Codex does not show agents or skills after restart |
| `agent-routing` | review mode or specialist selection is wrong for the branch |
| `context-budget` | context packets are too large or savings are repeatedly low |
| `review-quality` | findings lack evidence, severity is unclear, or false positives repeat |
| `privacy` | summary or sharing level is unclear or too specific |
| `docs` | the fix existed but the maintainer had to search for it |

## Repeated Blocker Rule

Create a product or docs fix when:

- the same category appears in at least two pilots
- one issue blocks first review entirely
- one issue would force sharing raw local state to explain the result
- a maintainer says the friction would stop them from rerunning Forgeflow

If none of those are true, run another pilot before changing product behavior.

## Next Action Mapping

| Dominant Category | Next Action |
|---|---|
| install, template-installer | improve installer output, manifest coverage, or clean-checkout verification |
| health, settings | improve `/forgeflow-health` diagnostics or settings docs |
| codex-discovery | improve Codex first-run verification and restart guidance |
| agent-routing, review-quality | tune routing docs, reviewer prompts, or evidence standards |
| context-budget | add examples, advisor guidance, or budget defaults based on evidence |
| privacy | tighten sharing boundaries and public-summary inspection |
| docs | move the missing step closer to the start path |

## Closeout

Record the result:

```yaml
decision: fix-now | run-another-pilot | expand-small-team | defer
reason:
linked_categories:
validation_needed:
```

Use [Pilot Adoption Comparison](Pilot-Adoption-Comparison.md) and [Team Adoption Criteria](Team-Adoption-Criteria.md) to decide whether the rollup supports expansion.