feat: add autonomy-readiness skill for retro agent

[ralphbean]

Summary

• Adds a new autonomy-readiness skill that provides a structured methodology for analyzing the delta between agent review and human review on a PR
• The skill is agent-agnostic (any agent can use it), with the retro agent as the initial consumer
• Wires the skill into retro's harness, agent frontmatter, and optimization goals as a 5th lens
• Adds scaffold test coverage for the new skill directory

What the skill does

Three-phase analysis:

1. Extract the delta — classify each human review finding as Matched (agent caught it), Gap (agent missed it), or Novel (agent-only)
2. Diagnose root causes — for gaps, walk a 5-item diagnostic checklist (missing context, tests, CI gates, skill guidance, documentation) to identify structural repo changes
3. Assess successes — for fully-matched PRs, identify patterns that could justify relaxing CODEOWNERS, protected paths, agent permissions, or auto-merge scope

Proposals follow a conservatism principle: smaller changes first, shadow mode before real autonomy, every proposal individually reversible.

Motivation

Nobody has auto-merge for review agent today. Getting there requires incremental trust-building. This skill lets the retro agent systematically propose per-repo changes that close review gaps and, when evidence supports it, propose specific autonomy increases with experiments and rollback criteria.

Design spec: docs/superpowers/specs/2026-06-22-autonomy-readiness-skill-design.md

Test plan

• go test ./internal/scaffold/ — all tests pass including TestHarnessesLoadAndValidate (validates skill directory exists) and TestFullsendRepoFilesExist (new entry)
• go test ./internal/skill/ — frontmatter parsing tests pass
• go test ./internal/harness/ — harness validation tests pass

[qodo-code-review]

PR Summary by Qodo

Add autonomy-readiness skill and wire it into the retro agent
✨ Enhancement 📝 Documentation 🧪 Tests ⚙️ Configuration changes 🕐 10-20 Minutes

Description

• Add an agent-agnostic "autonomy readiness" review-delta analysis methodology as a new skill.
• Wire the new skill into the retro harness and retro agent optimization goals.
• Extend scaffold tests to assert the new skill file exists in the fullsend-repo scaffold.

Diagram

graph TD
  H["retro.yaml"] --> Skill["autonomy-readiness skill"] --> Runner["Retro harness runner"] --> Agent["agents/retro.md"]
  T["scaffold_test.go"] --> Validate["Scaffold validation"] --> H

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Fold methodology into existing retro-analysis skill

• ➕ Fewer skill directories and less harness surface area
• ➕ Single place for retro workflow guidance
• ➖ Conflates timeline reconstruction with autonomy-readiness evaluation
• ➖ Harder to reuse the methodology outside retro or as a standalone lens

2. Make autonomy-readiness a structured output schema/tool instead of Markdown

• ➕ More machine-checkable outputs (e.g., explicit Matched/Gap/Novel objects)
• ➕ Easier aggregation across PRs for evidence-based autonomy proposals
• ➖ Requires schema changes and retro output pipeline updates
• ➖ Higher implementation cost and coordination vs. a lightweight skill document

Recommendation: The PR’s approach (a standalone, agent-agnostic skill plus minimal retro wiring) is the best incremental step: it keeps the methodology reusable, avoids schema/workflow churn, and leverages existing scaffold validation to prevent drift. If adoption proves valuable, consider a follow-up to add optional structured artifacts for aggregation, without replacing the Markdown guidance.

Files changed (6) +623 / -0

Enhancement (2) +115 / -0

retro.mdAdd autonomy-readiness skill + new retro optimization lens +2/-0

Add autonomy-readiness skill + new retro optimization lens

• Adds autonomy-readiness to the retro agent frontmatter skills list so it appears in the system prompt. Extends optimization goals with an explicit "Autonomy readiness" lens directing use of the new skill.

internal/scaffold/fullsend-repo/agents/retro.md

SKILL.mdAdd autonomy-readiness SKILL.md with 3-phase analysis framework +113/-0

Add autonomy-readiness SKILL.md with 3-phase analysis framework

• Creates a new skill directory containing an agent-agnostic methodology for comparing agent vs human review findings. Provides diagnostic categories for gaps, criteria for autonomy increases, and conservative experiment/rollback framing.

internal/scaffold/fullsend-repo/skills/autonomy-readiness/SKILL.md

Tests (1) +1 / -0

scaffold_test.goAssert new skill file exists in scaffold file list +1/-0

Assert new skill file exists in scaffold file list

• Extends 'TestFullsendRepoFilesExist' to include 'skills/autonomy-readiness/SKILL.md'. Ensures the embedded scaffold stays consistent with harness/agent wiring.

internal/scaffold/scaffold_test.go

Documentation (2) +506 / -0

2026-06-22-autonomy-readiness-skill.mdAdd implementation plan for autonomy-readiness skill +362/-0

Add implementation plan for autonomy-readiness skill

• Introduces a step-by-step implementation plan covering skill creation, retro harness/prompt wiring, and scaffold test updates. Documents expected commands and validation points (Go tests) for each task.

docs/superpowers/plans/2026-06-22-autonomy-readiness-skill.md

2026-06-22-autonomy-readiness-skill-design.mdAdd design spec for autonomy-readiness skill methodology +144/-0

Add design spec for autonomy-readiness skill methodology

• Defines the purpose, phases (delta extraction, gap diagnosis, success assessment), and proposal framing for autonomy-readiness. Specifies retro integration points and explicitly avoids schema/workflow changes.

docs/superpowers/specs/2026-06-22-autonomy-readiness-skill-design.md

Other (1) +1 / -0

retro.yamlWire autonomy-readiness into retro harness skills list +1/-0

Wire autonomy-readiness into retro harness skills list

• Adds the new skill path to the retro harness 'skills:' array so it is available during retro runs. Keeps existing harness behavior and scripts unchanged.

internal/scaffold/fullsend-repo/harness/retro.yaml

[github-actions]

Site preview

Preview: https://4ec19d47-site.fullsend-ai.workers.dev

Commit: ba16739ba58fee9c1860c9e7ec73fe59149a6bea

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:08 PM UTC · Completed 11:21 PM UTC
Commit: 0cbc959 · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

Medium

• [missing-documentation-update] docs/guides/user/customizing-with-skills.md:114 — The built-in skills table lists retro-analysis and finding-agent-runs as the Retro agent's skills but does not include the new autonomy-readiness skill being added in this PR. Users consulting this guide will not see the new skill as overloadable.
  Remediation: Add autonomy-readiness to the Retro agent row in the built-in skills table.

Previous run

Review

Findings

Medium

• [missing-documentation-update] docs/guides/user/customizing-with-skills.md:114 — The built-in skills table lists retro-analysis and finding-agent-runs as the Retro agent's skills but does not include the new autonomy-readiness skill being added in this PR. Users consulting this guide will not see the new skill as overloadable.
  Remediation: Add autonomy-readiness to the Retro agent row in the built-in skills table.

Low

• [missing-authorization] PR-level — This PR introduces a non-trivial feature (new skill + agent integration across 6 files, 606 lines) but has no linked issue. The PR includes extensive design rationale (362-line plan, 144-line spec) which substantially compensates, but linking an issue provides traceability for future retrospectives.

• [scope-coherence] internal/scaffold/fullsend-repo/agents/retro.md:535 — Optimization goal docs: add agent infrastructure problem document #5 introduces a scope expansion from workflow efficiency analysis to governance/autonomy proposals. The retro agent already has scope to "propose improvements to the system" and the design spec mentions configurable optimization goals as a future extension, so this is a natural evolution. The conservatism principle in the SKILL.md ("shadow mode before real autonomy, every proposal individually reversible") provides appropriate guardrails.

• [technical-accuracy] internal/scaffold/fullsend-repo/skills/autonomy-readiness/SKILL.md — The final paragraph recommends adding agent skills to the target repo's .claude/ directory, but the documented pattern in docs/guides/user/customizing-with-skills.md specifies .agents/skills/ as the canonical location with .claude/skills as a symlink for cross-runtime portability.
  Remediation: Revise to reference .agents/skills/ as the primary location.

• [implementation-deviation] internal/scaffold/fullsend-repo/skills/autonomy-readiness/SKILL.md — The implemented SKILL.md (96 lines) deviates from the plan document's specification (lines 37–180). The core methodology (3 phases, diagnostic checklist, proposal framing) is preserved, but the implementation consolidates subsections and adds novel .claude/ directory guidance not in the plan. Since both documents are new in this PR, this is a minor internal consistency concern.

• [skill-frontmatter-description-format] internal/scaffold/fullsend-repo/skills/autonomy-readiness/SKILL.md:3 — The skill frontmatter description uses 'on a PR' which is slightly more colloquial than some other skills, though within the range of existing style.

• [skill-list-harness-mismatch] internal/scaffold/fullsend-repo/agents/retro.md:10 — The agent frontmatter skills list includes retro-analysis, finding-agent-runs, and autonomy-readiness, but the harness config also includes agent-scaffolding. Pre-existing inconsistency not introduced by this PR, but the PR had an opportunity to fix it while modifying the same frontmatter block.

• [plan-content-model-reference] docs/superpowers/plans/2026-06-22-autonomy-readiness-skill.md:197 — The plan document references 'Claude claude-opus-4-6' in the Assisted-by trailer across five commit message examples. Minor cosmetic concern in documentation.

• [missing-documentation-update] docs/superpowers/specs/2026-05-04-retro-agent-design.md:89 — The retro agent design spec lists optimization goal examples but only shows the original set. The canonical goal list now has 5 goals. The spec uses "Examples:" explicitly, so this is minor.

• [undocumented-directory] README.md — Files added to docs/superpowers/plans/ and docs/superpowers/specs/ which are not documented in README.md. Pre-existing gap not introduced by this PR.

• [missing-documentation-update] docs/superpowers/plans/2026-05-04-retro-agent.md:593 — Historical retro agent implementation plan embeds an agent definition template with 4 optimization goals. Now 5 exist. Historical document; low priority.

Previous run

Review

Findings

Medium

• [missing-documentation-update] docs/guides/user/customizing-with-skills.md:114 — The built-in skills table lists retro-analysis and finding-agent-runs as the Retro agent's skills but does not include the new autonomy-readiness skill being added in this PR. Users consulting this guide will not see the new skill as overloadable.
  Remediation: Add autonomy-readiness to the Retro agent row in the built-in skills table.

Low

• [missing-authorization] PR-level — This PR introduces a non-trivial feature (new skill + agent integration across 6 files, 606 lines) but has no linked issue. The PR includes extensive design rationale (362-line plan, 144-line spec) which substantially compensates, but linking an issue provides traceability for future retrospectives.

• [scope-coherence] internal/scaffold/fullsend-repo/agents/retro.md:535 — Optimization goal docs: add agent infrastructure problem document #5 introduces a scope expansion from workflow efficiency analysis to governance/autonomy proposals. The retro agent already has scope to "propose improvements to the system" and the design spec mentions configurable optimization goals as a future extension, so this is a natural evolution. The conservatism principle in the SKILL.md ("shadow mode before real autonomy, every proposal individually reversible") provides appropriate guardrails.

• [technical-accuracy] internal/scaffold/fullsend-repo/skills/autonomy-readiness/SKILL.md — The final paragraph recommends adding agent skills to the target repo's .claude/ directory, but the documented pattern in docs/guides/user/customizing-with-skills.md specifies .agents/skills/ as the canonical location with .claude/skills as a symlink for cross-runtime portability.
  Remediation: Revise to reference .agents/skills/ as the primary location.

• [implementation-deviation] internal/scaffold/fullsend-repo/skills/autonomy-readiness/SKILL.md — The implemented SKILL.md (96 lines) deviates from the plan document's specification (lines 37–180). The core methodology (3 phases, diagnostic checklist, proposal framing) is preserved, but the implementation consolidates subsections and adds novel .claude/ directory guidance not in the plan. Since both documents are new in this PR, this is a minor internal consistency concern.

• [skill-frontmatter-description-format] internal/scaffold/fullsend-repo/skills/autonomy-readiness/SKILL.md:3 — The skill frontmatter description uses 'on a PR' which is slightly more colloquial than some other skills, though within the range of existing style.

• [skill-list-harness-mismatch] internal/scaffold/fullsend-repo/agents/retro.md:10 — The agent frontmatter skills list includes retro-analysis, finding-agent-runs, and autonomy-readiness, but the harness config also includes agent-scaffolding. Pre-existing inconsistency not introduced by this PR, but the PR had an opportunity to fix it while modifying the same frontmatter block.

• [plan-content-model-reference] docs/superpowers/plans/2026-06-22-autonomy-readiness-skill.md:197 — The plan document references 'Claude claude-opus-4-6' in the Assisted-by trailer across five commit message examples. Minor cosmetic concern in documentation.

• [missing-documentation-update] docs/superpowers/specs/2026-05-04-retro-agent-design.md:89 — The retro agent design spec lists optimization goal examples but only shows the original set. The canonical goal list now has 5 goals. The spec uses "Examples:" explicitly, so this is minor.

• [undocumented-directory] README.md — Files added to docs/superpowers/plans/ and docs/superpowers/specs/ which are not documented in README.md. Pre-existing gap not introduced by this PR.

• [missing-documentation-update] docs/superpowers/plans/2026-05-04-retro-agent.md:593 — Historical retro agent implementation plan embeds an agent definition template with 4 optimization goals. Now 5 exist. Historical document; low priority.

Previous run (2)

Review

Findings

Medium

• [missing-authorization] PR-level — This PR introduces a non-trivial feature (new skill + agent integration across 6 files, 619+ lines) but has no linked issue. The PR itself contains extensive design rationale (362-line plan, 144-line spec), which partially compensates, but non-trivial changes benefit from explicit authorization via a linked issue that states the problem being solved and expected outcomes.
  Remediation: Create a GitHub issue documenting (1) the problem this skill solves, (2) why it belongs in the retro agent, (3) expected outcomes, and link it to this PR.

• [scope-coherence] internal/scaffold/fullsend-repo/agents/retro.md:44 — Optimization goal docs: add agent infrastructure problem document #5 introduces a scope expansion from workflow efficiency analysis to governance/autonomy proposals. The existing 4 goals focus on operational metrics (review quality, rework rate, token cost, time to resolution). Goal docs: add agent infrastructure problem document #5 asks "could the repo grant it more autonomy for that class of change?" — shifting into meta-level questions about agent authority. The retro agent design spec (docs/superpowers/specs/2026-05-04-retro-agent-design.md) describes the agent as proposing workflow improvements, not governance changes. See also: [optimization-lens-numbering] finding at this location.
  Remediation: Clarify whether the retro agent's scope now includes proposing governance/autonomy changes, or whether this skill surfaces data for humans to decide. If the former, update the retro agent design spec to reflect the expanded scope.

• [missing-documentation-update] docs/guides/user/customizing-with-skills.md:114 — The built-in skills table lists retro-analysis and finding-agent-runs as the Retro agent's skills but does not include the new autonomy-readiness skill being added in this PR.
  Remediation: Add autonomy-readiness to the Retro agent row in the built-in skills table.

Low

• [optimization-lens-numbering] internal/scaffold/fullsend-repo/agents/retro.md:44 — Goal docs: add agent infrastructure problem document #5 is added to a list described as "in priority order." Position 5 naturally makes it lowest priority, which is reasonable for a new experimental lens. Minor clarity improvement possible. See also: [scope-coherence] finding at this location.

• [missing-documentation-update] docs/superpowers/specs/2026-05-04-retro-agent-design.md:89 — The retro agent design spec lists optimization goal examples but only shows the original set. The canonical goal list lives in agents/retro.md, so this is a minor housekeeping concern rather than a primary documentation gap.

• [undocumented-directory] docs/superpowers/plans/2026-06-22-autonomy-readiness-skill.md — Files are added to docs/superpowers/plans/ and docs/superpowers/specs/, which already exist with 12 plans and 16 specs but are not documented in README.md. Pre-existing gap, not introduced by this PR.

• [skill-list-order] internal/scaffold/fullsend-repo/agents/retro.md:10 — The agent frontmatter skills list adds autonomy-readiness as the third item. The harness config includes agent-scaffolding which is absent from frontmatter — minor pre-existing inconsistency.

• [missing-documentation-update] docs/superpowers/plans/2026-05-04-retro-agent.md:593 — The original retro agent implementation plan embeds an agent definition template with 4 optimization goals. Historical plan document; low priority to update.

---

Labels: PR adds a new skill for the retro agent, modifies harness configuration, and includes design documentation.

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:54 PM UTC · Completed 12:07 AM UTC
Commit: ba16739 · View workflow run →

[ralphbean]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 5:03 PM UTC · Completed 5:14 PM UTC
Commit: a00f6ce · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 4:13 PM UTC · Completed 4:19 PM UTC
Commit: ba16739 · View workflow run →

[fullsend-ai-retro]

Retro: PR #2539 — feat: add autonomy-readiness skill for retro agent

Timeline: Human-authored PR by ralphbean opened 2026-06-22, reviewed by the review agent (3 runs) and human reviewers, approved by ifireball 2026-06-24, merged same day.

Key observation: The human author (ralphbean) self-reviewed within 4 minutes of opening the PR and identified 4 substantive content quality issues in the skill definition — unnecessary "When to use" section (duplicated description metadata), unnecessary "Out of scope" section, overly-prescriptive "In-scope" enumeration that would limit agent creativity, and an unnecessary "Constraints" section. All four were addressed in commit ba16739. The review agent ran 3 times but missed all of these issues. The review agent's most notable finding was a medium "missing-documentation-update" (skills table in docs not updated), which was a valid catch, and a medium "scope-coherence" concern that was arguably a false positive since expanding the retro agent's scope was the PR's explicit purpose.

Skipped proposals (existing coverage):

• Multiple review runs / token waste: well-covered by Add per-PR review budget to cap runaway review dispatches #2599, Reduce redundant review dispatches triggered by non-code events #893, Review agent accumulates redundant internal iterations on clean diffs #1370, Review-fix race condition causes duplicate review cycles and wasted tokens #1557
• False positives on intentional scope changes: partially covered by Review intent-coherence sub-agent should treat human review feedback as scope authorization #2253 (intent-coherence sub-agent should treat human feedback as scope authorization). The specific variant here (PR's own title/description as scope authorization) is close enough to fold into Review intent-coherence sub-agent should treat human review feedback as scope authorization #2253.
• Skill definition repo-specific references: covered by Review agent should detect repo-specific references in scaffolded skill definitions #1908, Code agent should treat scaffolded skill definitions as generic templates #1909

1 new proposal filed — review agent content quality gap for agent-facing documents.

Proposals filed

• Review agent should assess content quality and redundancy in agent-facing documents (in fullsend-ai/fullsend)