feed-the-machine 1.6.1 → 1.7.1

package/ftm-retro/references/protocols/SCORING-RUBRICS.md

@@ -1,89 +1,89 @@
-# Scoring Rubrics — All 5 Dimensions
-
-Detailed rubrics for ftm-retro scoring. Each dimension is scored 0–10 with a citation to specific data. Do not estimate without evidence — if data is missing, note it and score conservatively.
-
----
-
-## Dimension 1: Wave Parallelism Efficiency (0–10)
-
-Were independent tasks actually dispatched in parallel? Could more tasks have been parallelized?
-
-- **10**: Every task that could run in parallel did. No serial bottlenecks where parallelism was possible.
-- **7–9**: Minor serial steps that could have been parallel (e.g., final post-processing tasks run sequentially).
-- **4–6**: Significant parallelism opportunities missed. Tasks that had no dependencies ran serially.
-- **1–3**: Nearly all tasks ran serially despite having no dependencies on each other.
-- **0**: Everything was serial regardless of dependency structure.
-
-Evidence to cite: wave structure from PROGRESS.md, task dependency graph, agent dispatch timestamps.
-
----
-
-## Dimension 2: Audit Pass Rate (0–10)
-
-What percentage of tasks passed ftm-audit on the first attempt?
-
-- **10**: 100% first-pass. No task needed a fix cycle.
-- **8**: 90%+ first-pass. One or two tasks needed minor fixes.
-- **6**: 75–89% first-pass.
-- **4**: 50–74% first-pass. Roughly half the tasks needed audit remediation.
-- **2**: Below 50% first-pass.
-- **0**: Every single task failed audit on the first attempt.
-
-Evidence to cite: per-task audit results (pass/fail counts, auto-fix counts, manual-fix counts).
-
----
-
-## Dimension 3: Codex Gate Pass Rate (0–10)
-
-What percentage of waves passed the ftm-codex-gate on the first attempt?
-
-- **10**: All waves passed on first gate run.
-- **7–9**: One wave needed a fix-and-retry.
-- **4–6**: Multiple waves needed retries.
-- **1–3**: Most waves failed the gate at least once.
-- **0**: Every wave failed the gate.
-
-Evidence to cite: codex gate results per wave (pass/fail, failure types).
-
----
-
-## Dimension 4: Retry and Fix Count (0–10)
-
-How many total review-fix cycles were needed across all tasks and waves? Lower is better.
-
-Formula: `score = max(0, 10 - (total_retries / task_count) * 5)`
-
-- **10**: Zero retries.
-- **8**: Fewer than 0.5 retries per task on average.
-- **6**: 0.5–1.0 retries per task.
-- **4**: 1–2 retries per task.
-- **2**: 2–3 retries per task.
-- **0**: More than 3 retries per task on average.
-
-Evidence to cite: total retries, broken down by type (audit fix, codex gate retry, manual intervention).
-
----
-
-## Dimension 5: Execution Smoothness (0–10)
-
-Subjective but evidence-grounded assessment. Were there blockers, ambiguous plan steps, confusing errors, or required manual interventions?
-
-- **10**: Fully autonomous from start to finish. No blockers, no ambiguity, no manual steps.
-- **7–9**: Minor friction — one clarification needed, one unexpected error handled gracefully.
-- **4–6**: Moderate friction — multiple ambiguities, one blocker that paused execution, one manual intervention.
-- **1–3**: Significant friction — repeated blockers, unclear plan steps that caused wrong-direction work, multiple manual interventions.
-- **0**: Execution could not proceed without constant human steering.
-
-Evidence to cite: error log entries, any manual interventions recorded in PROGRESS.md, plan ambiguities encountered.
-
----
-
-## Scoring Principles
-
-### Evidence-first scoring
-
-Every score needs a citation. "Tasks passed audit" is not a citation. "12/14 tasks passed audit on first attempt; Tasks 3 and 9 each needed one auto-fix cycle" is a citation. If the data to score a dimension is genuinely unavailable, note the gap explicitly and score conservatively (assume worst case for that dimension).
-
-### No vibes
-
-Do not write "the execution felt smooth" or "agents seemed efficient." Write "0 manual interventions were required and all errors were caught and auto-resolved by ftm-audit Phase 2." The report is read by future executions that need to calibrate behavior, not by humans looking for encouragement.
+# Scoring Rubrics — All 5 Dimensions
+
+Detailed rubrics for ftm-retro scoring. Each dimension is scored 0–10 with a citation to specific data. Do not estimate without evidence — if data is missing, note it and score conservatively.
+
+---
+
+## Dimension 1: Wave Parallelism Efficiency (0–10)
+
+Were independent tasks actually dispatched in parallel? Could more tasks have been parallelized?
+
+- **10**: Every task that could run in parallel did. No serial bottlenecks where parallelism was possible.
+- **7–9**: Minor serial steps that could have been parallel (e.g., final post-processing tasks run sequentially).
+- **4–6**: Significant parallelism opportunities missed. Tasks that had no dependencies ran serially.
+- **1–3**: Nearly all tasks ran serially despite having no dependencies on each other.
+- **0**: Everything was serial regardless of dependency structure.
+
+Evidence to cite: wave structure from PROGRESS.md, task dependency graph, agent dispatch timestamps.
+
+---
+
+## Dimension 2: Audit Pass Rate (0–10)
+
+What percentage of tasks passed ftm-audit on the first attempt?
+
+- **10**: 100% first-pass. No task needed a fix cycle.
+- **8**: 90%+ first-pass. One or two tasks needed minor fixes.
+- **6**: 75–89% first-pass.
+- **4**: 50–74% first-pass. Roughly half the tasks needed audit remediation.
+- **2**: Below 50% first-pass.
+- **0**: Every single task failed audit on the first attempt.
+
+Evidence to cite: per-task audit results (pass/fail counts, auto-fix counts, manual-fix counts).
+
+---
+
+## Dimension 3: Codex Gate Pass Rate (0–10)
+
+What percentage of waves passed the ftm-codex-gate on the first attempt?
+
+- **10**: All waves passed on first gate run.
+- **7–9**: One wave needed a fix-and-retry.
+- **4–6**: Multiple waves needed retries.
+- **1–3**: Most waves failed the gate at least once.
+- **0**: Every wave failed the gate.
+
+Evidence to cite: codex gate results per wave (pass/fail, failure types).
+
+---
+
+## Dimension 4: Retry and Fix Count (0–10)
+
+How many total review-fix cycles were needed across all tasks and waves? Lower is better.
+
+Formula: `score = max(0, 10 - (total_retries / task_count) * 5)`
+
+- **10**: Zero retries.
+- **8**: Fewer than 0.5 retries per task on average.
+- **6**: 0.5–1.0 retries per task.
+- **4**: 1–2 retries per task.
+- **2**: 2–3 retries per task.
+- **0**: More than 3 retries per task on average.
+
+Evidence to cite: total retries, broken down by type (audit fix, codex gate retry, manual intervention).
+
+---
+
+## Dimension 5: Execution Smoothness (0–10)
+
+Subjective but evidence-grounded assessment. Were there blockers, ambiguous plan steps, confusing errors, or required manual interventions?
+
+- **10**: Fully autonomous from start to finish. No blockers, no ambiguity, no manual steps.
+- **7–9**: Minor friction — one clarification needed, one unexpected error handled gracefully.
+- **4–6**: Moderate friction — multiple ambiguities, one blocker that paused execution, one manual intervention.
+- **1–3**: Significant friction — repeated blockers, unclear plan steps that caused wrong-direction work, multiple manual interventions.
+- **0**: Execution could not proceed without constant human steering.
+
+Evidence to cite: error log entries, any manual interventions recorded in PROGRESS.md, plan ambiguities encountered.
+
+---
+
+## Scoring Principles
+
+### Evidence-first scoring
+
+Every score needs a citation. "Tasks passed audit" is not a citation. "12/14 tasks passed audit on first attempt; Tasks 3 and 9 each needed one auto-fix cycle" is a citation. If the data to score a dimension is genuinely unavailable, note the gap explicitly and score conservatively (assume worst case for that dimension).
+
+### No vibes
+
+Do not write "the execution felt smooth" or "agents seemed efficient." Write "0 manual interventions were required and all errors were caught and auto-resolved by ftm-audit Phase 2." The report is read by future executions that need to calibrate behavior, not by humans looking for encouragement.

package/ftm-retro/references/templates/REPORT-FORMAT.md

@@ -1,109 +1,109 @@
-# Report Format — Retro Output Template
-
-This is the exact format for all retro report files saved to `~/.claude/ftm-retros/`.
-
----
-
-## File Naming
-
-Save to: `~/.claude/ftm-retros/{plan-slug}-{YYYY-MM-DD}.md`
-
-### Slug Generation
-
-Take the plan title, lowercase it, replace spaces with hyphens, strip all non-alphanumeric characters except hyphens.
-
-Examples:
-- "FTM Ecosystem Expansion" → `ftm-ecosystem-expansion`
-- "Fix Auth Bug + Rate Limiting" → `fix-auth-bug-rate-limiting`
-- "v2.0 API Refactor" → `v20-api-refactor`
-
----
-
-## Report Template
-
-```markdown
-# Retro: {Plan Title}
-
-**Date:** {YYYY-MM-DD}
-**Plan:** {absolute path to plan file}
-**Duration:** {total execution time, e.g. "47 minutes"}
-
-## Scores
-
-| Dimension | Score | Notes |
-|-----------|-------|-------|
-| Wave Parallelism | X/10 | {1-sentence justification with data} |
-| Audit Pass Rate | X/10 | {N}/{total} tasks first-pass |
-| Codex Gate Pass Rate | X/10 | {N}/{total} waves first-pass |
-| Retry/Fix Count | X/10 | {total retries} across {N} tasks |
-| Execution Smoothness | X/10 | {1-sentence justification} |
-
-**Overall: {sum}/50**
-
-## Raw Data
-
-- Tasks: {N}
-- Waves: {N}
-- Agents spawned: {N}
-- Audit findings: {N} total ({N} auto-fixed, {N} manual)
-- Codex gate results: Wave 1: pass | Wave 2: fail → pass | Wave 3: pass
-- Errors/blockers: {list any, or "none"}
-
-## What Went Well
-
-{2–4 specific observations, each grounded in a data point or task number.}
-
-Example format:
-- **Task 3 (auth middleware)** completed in a single commit with zero audit findings. The agent prompt had clear acceptance criteria and a scoped file list — the agent never wandered.
-- **Wave 2 parallelism** was fully utilized: all 4 tasks dispatched simultaneously, cutting estimated serial time from ~32 minutes to ~9 minutes.
-
-## What Was Slow
-
-{2–4 specific bottlenecks with timing data or retry counts where available.}
-
-Example format:
-- **ftm-audit Phase 1 (knip)** repeated full project analysis for each task in wave 3, even though tasks only touched 2–3 files each. Added ~40s × 5 tasks = ~3.5 minutes of unnecessary scanning.
-- **Task 7 needed 3 audit fix cycles** due to an import path that kept regenerating incorrectly. The agent prompt did not specify the alias configuration in tsconfig.paths.
-
-## Proposed Improvements
-
-{3–5 specific, actionable suggestions. Each must identify: which skill to change, what to change exactly, and why it would help.}
-
-Format each as:
-**N. {Short title}** — {Skill to change} — {Specific change} — {Expected impact}
-
-Examples:
-1. **Cache knip results within a wave** — ftm-audit — In Phase 1, check whether knip results are already cached for the current wave (via a temp file at `/tmp/ftm-knip-cache-{wave-id}.json`). Only re-run knip if the cache is missing or if the files changed by this task differ from cached scope. Expected: 3× speedup for ftm-audit on large projects with many tasks per wave.
-2. **Dispatch Instrumentor and Researcher in parallel** — ftm-debug — These two agents have no shared state and currently run sequentially. Dispatch them simultaneously. Expected: ~40% reduction in ftm-debug total runtime.
-3. **Add tsconfig.paths to agent context for TypeScript projects** — ftm-executor — When generating agent prompts for TypeScript tasks, include the relevant `paths` aliases from `tsconfig.json`. Expected: eliminates the import-alias regeneration loop that caused 3 retries on Task 7.
-
-## Pattern Analysis
-
-{Only include this section if past retros exist in ~/.claude/ftm-retros/}
-
-### Recurring Issues
-
-{List problems that appeared in 2 or more retros. Format: "Issue description — appeared in: retro-slug-1, retro-slug-2"}
-
-### Score Trends
-
-{Compare overall scores across retros. Are they improving, declining, or stable? Cite actual numbers.}
-
-Example: Overall scores: 32/50 → 38/50 → 41/50 across the last 3 retros. Parallelism and smoothness improving; audit pass rate stuck at 6/10 for all three runs.
-
-### Unaddressed Suggestions
-
-{List proposed improvements from past retros that have not yet been implemented. These get escalated — flag them explicitly.}
-
-Format: "**[ESCALATED]** {suggestion} — first proposed in {retro-slug-date}, appeared {N} times"
-```
-
----
-
-## Improvement Specificity Standard
-
-"Improve parallelism" is not an improvement proposal. "Add a dependency pre-check step to ftm-executor Phase 2 that flags tasks with no declared dependencies as parallelizable, and warn when they are dispatched serially" is an improvement proposal. Every proposed improvement must be concrete enough that a future session could implement it from the description alone without asking clarifying questions.
-
-## Pattern Escalation Standard
-
-Recurring issues that have appeared in 3+ retros without being addressed should be flagged with `[ESCALATED - 3+ occurrences]` and moved to the top of the Proposed Improvements list. These are systemic problems, not one-off noise.
+# Report Format — Retro Output Template
+
+This is the exact format for all retro report files saved to `~/.claude/ftm-retros/`.
+
+---
+
+## File Naming
+
+Save to: `~/.claude/ftm-retros/{plan-slug}-{YYYY-MM-DD}.md`
+
+### Slug Generation
+
+Take the plan title, lowercase it, replace spaces with hyphens, strip all non-alphanumeric characters except hyphens.
+
+Examples:
+- "FTM Ecosystem Expansion" → `ftm-ecosystem-expansion`
+- "Fix Auth Bug + Rate Limiting" → `fix-auth-bug-rate-limiting`
+- "v2.0 API Refactor" → `v20-api-refactor`
+
+---
+
+## Report Template
+
+```markdown
+# Retro: {Plan Title}
+
+**Date:** {YYYY-MM-DD}
+**Plan:** {absolute path to plan file}
+**Duration:** {total execution time, e.g. "47 minutes"}
+
+## Scores
+
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| Wave Parallelism | X/10 | {1-sentence justification with data} |
+| Audit Pass Rate | X/10 | {N}/{total} tasks first-pass |
+| Codex Gate Pass Rate | X/10 | {N}/{total} waves first-pass |
+| Retry/Fix Count | X/10 | {total retries} across {N} tasks |
+| Execution Smoothness | X/10 | {1-sentence justification} |
+
+**Overall: {sum}/50**
+
+## Raw Data
+
+- Tasks: {N}
+- Waves: {N}
+- Agents spawned: {N}
+- Audit findings: {N} total ({N} auto-fixed, {N} manual)
+- Codex gate results: Wave 1: pass | Wave 2: fail → pass | Wave 3: pass
+- Errors/blockers: {list any, or "none"}
+
+## What Went Well
+
+{2–4 specific observations, each grounded in a data point or task number.}
+
+Example format:
+- **Task 3 (auth middleware)** completed in a single commit with zero audit findings. The agent prompt had clear acceptance criteria and a scoped file list — the agent never wandered.
+- **Wave 2 parallelism** was fully utilized: all 4 tasks dispatched simultaneously, cutting estimated serial time from ~32 minutes to ~9 minutes.
+
+## What Was Slow
+
+{2–4 specific bottlenecks with timing data or retry counts where available.}
+
+Example format:
+- **ftm-audit Phase 1 (knip)** repeated full project analysis for each task in wave 3, even though tasks only touched 2–3 files each. Added ~40s × 5 tasks = ~3.5 minutes of unnecessary scanning.
+- **Task 7 needed 3 audit fix cycles** due to an import path that kept regenerating incorrectly. The agent prompt did not specify the alias configuration in tsconfig.paths.
+
+## Proposed Improvements
+
+{3–5 specific, actionable suggestions. Each must identify: which skill to change, what to change exactly, and why it would help.}
+
+Format each as:
+**N. {Short title}** — {Skill to change} — {Specific change} — {Expected impact}
+
+Examples:
+1. **Cache knip results within a wave** — ftm-audit — In Phase 1, check whether knip results are already cached for the current wave (via a temp file at `/tmp/ftm-knip-cache-{wave-id}.json`). Only re-run knip if the cache is missing or if the files changed by this task differ from cached scope. Expected: 3× speedup for ftm-audit on large projects with many tasks per wave.
+2. **Dispatch Instrumentor and Researcher in parallel** — ftm-debug — These two agents have no shared state and currently run sequentially. Dispatch them simultaneously. Expected: ~40% reduction in ftm-debug total runtime.
+3. **Add tsconfig.paths to agent context for TypeScript projects** — ftm-executor — When generating agent prompts for TypeScript tasks, include the relevant `paths` aliases from `tsconfig.json`. Expected: eliminates the import-alias regeneration loop that caused 3 retries on Task 7.
+
+## Pattern Analysis
+
+{Only include this section if past retros exist in ~/.claude/ftm-retros/}
+
+### Recurring Issues
+
+{List problems that appeared in 2 or more retros. Format: "Issue description — appeared in: retro-slug-1, retro-slug-2"}
+
+### Score Trends
+
+{Compare overall scores across retros. Are they improving, declining, or stable? Cite actual numbers.}
+
+Example: Overall scores: 32/50 → 38/50 → 41/50 across the last 3 retros. Parallelism and smoothness improving; audit pass rate stuck at 6/10 for all three runs.
+
+### Unaddressed Suggestions
+
+{List proposed improvements from past retros that have not yet been implemented. These get escalated — flag them explicitly.}
+
+Format: "**[ESCALATED]** {suggestion} — first proposed in {retro-slug-date}, appeared {N} times"
+```
+
+---
+
+## Improvement Specificity Standard
+
+"Improve parallelism" is not an improvement proposal. "Add a dependency pre-check step to ftm-executor Phase 2 that flags tasks with no declared dependencies as parallelizable, and warn when they are dispatched serially" is an improvement proposal. Every proposed improvement must be concrete enough that a future session could implement it from the description alone without asking clarifying questions.
+
+## Pattern Escalation Standard
+
+Recurring issues that have appeared in 3+ retros without being addressed should be flagged with `[ESCALATED - 3+ occurrences]` and moved to the top of the Proposed Improvements list. These are systemic problems, not one-off noise.

package/ftm-retro.yml

@@ -1,2 +1,2 @@
-name: ftm-retro
-description: Post-execution self-assessment skill. Automatically triggered after ftm-executor completes a plan. Scores execution across 5 dimensions, identifies what went well and what was slow, writes structured report with improvement suggestions. Use when user says "retro", "retrospective", "how did that go", "execution review", "self-assessment", "ftm retro".
+name: ftm-retro
+description: Post-execution self-assessment skill. Automatically triggered after ftm-executor completes a plan. Scores execution across 5 dimensions, identifies what went well and what was slow, writes structured report with improvement suggestions. Use when user says "retro", "retrospective", "how did that go", "execution review", "self-assessment", "ftm retro".