Skip to content

feat: add /hyper-plan skill — recursive codebase improvement with convergence scoring#166

Open
ShaheerKhawaja wants to merge 3 commits intogarrytan:mainfrom
ShaheerKhawaja:feat/hyper-plan-v2
Open

feat: add /hyper-plan skill — recursive codebase improvement with convergence scoring#166
ShaheerKhawaja wants to merge 3 commits intogarrytan:mainfrom
ShaheerKhawaja:feat/hyper-plan-v2

Conversation

@ShaheerKhawaja
Copy link

@ShaheerKhawaja ShaheerKhawaja commented Mar 18, 2026

Summary

Adds /hyper-plan, a new skill that chains /plan-ceo-review/plan-eng-review → execute fixes → /qa into an iterative loop with LLM-as-Judge convergence control. Treats codebase quality like gradient descent — each iteration targets the 2 weakest dimensions until the overall grade hits the target (default 8.0/10).

What PR #144 got wrong

Submitted a raw SKILL.md with no .tmpl template and no registration in the build pipeline. Feedback: "Single raw SKILL.md, no .tmpl template. Closing."

What's fixed

  • Proper .tmpl template with {{PREAMBLE}}, {{BASE_BRANCH_DETECT}}, and {{REVIEW_DASHBOARD}} placeholders
  • Registered in gen-skill-docs.ts findTemplates() candidates
  • Generated SKILL.md committed alongside template — --dry-run passes
  • Bisected commits (template → registration → generated output)

Features

  • 10-dimension quality rubric with specific evidence requirements per score level (file:line citations required)
  • Oscillation detection — if a dimension changes direction 3+ times (up→down→up), it's locked to prevent thrashing
  • Degradation tolerance — ≤0.5 score decrease is normal re-scoring variance, only HALT on >0.5 drops
  • Focus narrowing — iterations 2+ review only the 2 lowest-scoring dimensions, with graduation at 8.0+
  • Validation gate before every commit (lint + types + tests must pass)
  • Artifact trail — every iteration's findings and scores saved to .hyper-plan/

How it works

Baseline → Review (all 10 dims) → Fix P0+P1 → Verify via /qa → Re-score → Convergence check
                                                                              ↓
                                                              SUCCESS (≥ target) → stop
                                                              DEGRADED (>0.5 drop) → halt
                                                              OSCILLATING (3+ flips) → lock dim
                                                              CONVERGED (<0.2 delta × 2) → stop
                                                              MAX_REACHED → stop
                                                              CONTINUE → focus 2 weakest → loop

Test plan

  • bun run gen:skill-docs — produces hyper-plan/SKILL.md
  • bun run gen:skill-docs --dry-run — all FRESH
  • bun test — Tier 1 passes
  • bun run skill:check — freshness check passes
  • Only hyper-plan/ and scripts/gen-skill-docs.ts changed vs upstream/main

Muhammad Shaheer Khawaja and others added 3 commits March 18, 2026 01:25
Recursive codebase improvement with convergence scoring. Chains
/plan-ceo-review → /plan-eng-review → execute fixes → /qa into
an iterative loop with LLM-as-Judge convergence control.

Features:
- 10-dimension quality rubric with file:line evidence requirements
- Oscillation detection (lock thrashing dimensions after 3 direction changes)
- Degradation tolerance (≤0.5 variance is noise, >0.5 halts)
- Focus narrowing (iterations 2+ target only 2 weakest dimensions)
- Validation gate before every commit (lint + types + tests)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add hyper-plan/SKILL.md.tmpl to findTemplates() candidates list
so the build pipeline resolves {{PREAMBLE}}, {{BASE_BRANCH_DETECT}},
and {{REVIEW_DASHBOARD}} placeholders.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Output of `bun run gen:skill-docs` — resolves {{PREAMBLE}},
{{BASE_BRANCH_DETECT}}, and {{REVIEW_DASHBOARD}} placeholders
from the hyper-plan template.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant