Add junior-to-senior adversarial plan review skill

Treats agent-generated plans as junior work and constructs a senior
reviewer grounded in codebase research plus web research of current
best practices. Diagnoses altitude failures (fog: vague on hard parts;
tunnel: granular with no product vision), reviews adversarially with
evidence-backed findings, and rewrites the plan into a scoped,
state-of-the-art version with product decisions surfaced as open
questions.

Includes references for the review rubric (altitude tests, vague-word
blacklist, severity calibration) and the research playbook (code and
web research tracks, source quality ranking, stop conditions).

https://claude.ai/code/session_01EXN9BXWy6933G7RNQmmUU5

CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This repo publishes four Julius Brussee agent skills for now: `caveman`, `interface-kit`, `grill-me`, and `loop-factory`. Treat it as an installable skill collection, not a product website.
+This repo publishes five Julius Brussee agent skills for now: `caveman`, `interface-kit`, `grill-me`, `loop-factory`, and `junior-to-senior`. Treat it as an installable skill collection, not a product website.
 
 ## Editing Rules
 

README.md

@@ -1,13 +1,14 @@
 # Julius Skills
 
-Four personal agent skills for now: Caveman base, Interface Kit, Grill Me, and Loop Factory.
+Five personal agent skills for now: Caveman base, Interface Kit, Grill Me, Loop Factory, and Junior to Senior.
 
-This repo is shaped by four things:
+This repo is shaped by five things:
 
 - **Caveman** - 70k-star token compression without technical loss. Small mouth, big brain.
 - **Interface Kit** - accessible, performant interfaces with strong aesthetic direction, not generic AI slop.
 - **Grill Me** - calibrated pressure before hard critique, so challenge matches user knowledge and comfort.
 - **Loop Factory** - spec-driven agent loop where tasks move through inbox → active → archive with a real review gate.
+- **Junior to Senior** - adversarial senior review that treats agent output as junior work and upgrades it with codebase + web research.
 
 Point is control. Agents should be terse when talking, precise when building interfaces, calibrated when challenging plans, and disciplined when running build loops.
 
@@ -90,6 +91,18 @@ Use when you want:
 
 Pairs with the [Loop-Factory](https://github.com/JuliusBrussee/Loop-Factory) repo, which ships the CLI and native Claude/Codex adapters.
 
+### `junior-to-senior`
+
+Adversarial review skill for agent-generated plans. Treats the current output as the work of a junior, then constructs a senior reviewer grounded in codebase research and web research of current best practices. Diagnoses altitude failures — plans that are foggy on the hard parts or tunneled into details with no product vision — and rewrites them into a scoped, state-of-the-art version with evidence behind every finding.
+
+Use when you want:
+
+- a staff-engineer-grade review of a plan before committing to it
+- plans that commit on interfaces, versions, and failure modes instead of hand-waving
+- best practices refreshed past the model's training cutoff via live web research
+- a clear delta between the original plan and the upgraded one
+- product decisions surfaced as open questions instead of silently invented
+
 ## Interface Kit Standard
 
 If a repo has `DESIGN.md`, it wins. Otherwise UI work should still have a point of view:

skills/junior-to-senior/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: junior-to-senior
+description: Adversarial senior-engineer review for agent-generated plans, designs, and architectures. Treats the current output as junior work, constructs a senior reviewer whose domain expertise comes from live codebase research plus web research of current best practices, diagnoses altitude failures (too vague or too granular), then rewrites the plan into a scoped, state-of-the-art version. Use when the user says "junior to senior", "senior review", "review this like a staff engineer", when a plan feels hand-wavy or lost in details, or before committing to any agent-written plan.
+---
+
+# Junior to Senior
+
+Assume the plan in front of you was written by a capable junior: fluent, confident, and trained on the past. Build a senior reviewer that is grounded in two things the junior was not — **this codebase as it actually exists** and **the state of the art as it exists today** — and let the senior tear the plan down and rebuild it.
+
+This skill exists because agent-generated plans fail at two altitudes:
+
+- **Fog** — the plan describes the high level fine ("add caching", "handle auth", "make it scalable") but never commits on the hard parts. No interfaces, no data shapes, no failure handling, no named libraries. An engineer reading it still has to make every real decision themselves.
+- **Tunnel** — the plan dives into function signatures and file diffs but has no product vision. No statement of who this is for, what success means, what is out of scope, or why this approach beats the boring alternative. It optimizes a local detail while the shape of the feature is still wrong.
+
+Both are altitude failures. The senior's job is to drag the plan to the right altitude *and* upgrade its substance past the model's training cutoff.
+
+## The cardinal rule
+
+**Every senior finding needs evidence.** A claim about the codebase cites a file and line. A claim about best practice cites a fetched source — official docs, release notes, an RFC, a postmortem — with a date. If web research is unavailable, the finding is labeled `[training-data, unverified]` so stale knowledge is never laundered as current truth. A senior who argues from vibes is just a louder junior.
+
+## Phase 0: Capture the junior artifact
+
+Identify exactly what is under review:
+
+- A plan the agent just produced in this conversation (the default — including your own output from a moment ago).
+- A pasted plan, design doc, RFC, or issue description.
+- A planning document in the repo the user points at.
+
+Freeze it. Quote or restate the artifact in full before reviewing so the review targets a fixed text, not a moving memory of it. If there is no artifact yet, say so and offer to either generate the junior draft first or review the user's existing idea — do not review thin air.
+
+## Phase 1: Construct the senior
+
+The senior is not a tone of voice. It is a reviewer profile built from research done *now*. Skipping this phase and going straight to critique produces generic review slop.
+
+### 1a. Extract the domains
+
+List the 2-5 load-bearing technical domains the plan touches (e.g., "Postgres schema migration", "React server components", "OAuth token refresh", "vector search at 10M rows"). For each, write one sentence on what a staff-level engineer in that domain would refuse to let slide. This list drives all research that follows.
+
+### 1b. Code research — what is true here
+
+Investigate the repository before judging the plan against it:
+
+- Existing conventions and architecture the plan must fit (or explicitly break, with justification).
+- Actual versions in lockfiles/manifests — a plan recommending an API that the pinned version doesn't have is a blocker.
+- Prior art: similar features already in the codebase, ADRs, migrations, test patterns.
+- Real constraints the junior plan ignored: build system, deploy targets, performance budgets, existing data.
+
+Use a subagent (e.g. `Explore`) for broad sweeps so the review context stays clean.
+
+### 1c. Web research — what is true now
+
+For each load-bearing decision in the plan, search for the current state of the art. The junior's knowledge ends at a training cutoff; the senior's must not. Prioritize primary sources (official docs, changelogs, release notes, maintainer posts) and check dates. You are looking for three kinds of delta:
+
+- **Deprecations** — the plan's approach is now discouraged or removed.
+- **Supersessions** — a newer pattern/library/API has clearly won since the cutoff.
+- **Hard-won lessons** — published postmortems, benchmarks, or security advisories that change the tradeoff.
+
+Query patterns, source-quality ranking, and when to stop are in **[references/research-playbook.md](references/research-playbook.md)**. If web access is unavailable, proceed on code research alone and mark every best-practice claim `[training-data, unverified]`.
+
+### 1d. Isolation
+
+When the harness supports subagents, run the senior review in a context-isolated subagent that receives the frozen artifact and the research findings but *not* the reasoning that produced the junior plan. Self-review in the same context anchors on its own justifications; isolation is what makes the review adversarial rather than confirmatory.
+
+## Phase 2: Diagnose the altitude
+
+Before line-by-line critique, classify the artifact: **fog**, **tunnel**, or **mixed** (most real plans fog the hard parts and tunnel on the easy ones — flag each section separately).
+
+Fog test — for every component the plan names, can a competent engineer start tomorrow without making a product or architecture decision themselves? Tunnel test — does the plan state who this is for, what success looks like, what is explicitly out of scope, and why this approach beat the obvious alternative?
+
+The full diagnostic checklists, the vague-word blacklist ("simple", "scalable", "handle gracefully", "robust", ...), and severity definitions are in **[references/review-rubric.md](references/review-rubric.md)**.
+
+## Phase 3: Adversarial review
+
+The senior reviews the frozen artifact against three lenses: codebase reality (1b), current state of the art (1c), and altitude (Phase 2). Rules of engagement:
+
+- Every vague phrase gets challenged with the concrete question it is hiding from.
+- Every named technology gets a version and a reason; every unnamed one ("a queue", "some cache") gets named or the choice gets flagged as an open decision.
+- Every data shape that crosses a boundary gets written down.
+- Every plan gets asked: what is the rollback, what is the migration, what breaks at 10x.
+- Steelman before attacking: state the strongest version of the junior's choice, then show why it still loses (or concede that it wins — agreeing with the junior when the evidence supports it is a valid senior outcome, not a failure of the skill).
+
+Findings use three severities — **blocker** (plan fails as written), **major** (works but meaningfully worse than SOTA or misfit to the repo), **minor** (polish) — each with evidence and a concrete fix. Definitions and examples: **[references/review-rubric.md](references/review-rubric.md)**.
+
+## Phase 4: Promote the plan
+
+Critique without a rewrite is just complaining. Produce the senior version of the plan with this shape:
+
+1. **Goal and non-goals** — one paragraph of product intent; explicit out-of-scope list.
+2. **Decisions** — each load-bearing choice with the chosen option, version, rationale, the strongest rejected alternative, and the evidence (file ref or source link).
+3. **Design at the right altitude** — interfaces, data shapes, and failure handling for the hard parts; deliberately coarse strokes for the routine parts.
+4. **Sequencing** — milestones with an observable verification step each ("done" must be checkable, not vibes).
+5. **Risks and rollback** — what is hardest to undo and the escape hatch.
+6. **Open questions for a human** — product decisions the senior is *not* allowed to invent. Scoping is the senior's job; product direction is not.
+
+## Output format
+
+Deliver two artifacts, review first:
+
+```markdown
+## Senior Review
+
+**Altitude diagnosis:** fog | tunnel | mixed — one-sentence justification.
+
+### Blockers
+- [B1] Finding — evidence (file:line or source+date) — fix.
+
+### Major
+- [M1] ...
+
+### Minor
+- [m1] ...
+
+### What the junior got right
+- Credit where due; preserved in the rewrite.
+
+## Promoted Plan (v2)
+[Phase 4 structure]
+
+## Delta summary
+- 3-6 bullets: what changed from junior to senior and why.
+
+## Open questions for you
+- Product decisions that need a human.
+```
+
+## Boundaries
+
+- The senior scopes and upgrades; it does **not** invent product direction. Genuine product choices go to "Open questions", not into the rewrite.
+- Never silently replace the junior plan — the user sees the review, the rewrite, and the delta, and decides.
+- If research contradicts the user's stated preference, present the evidence and defer; the user may have context the senior lacks.
+- A review with zero blockers and zero majors is a legitimate result. Say "this plan holds" and stop — do not manufacture findings to look rigorous.

skills/junior-to-senior/references/research-playbook.md

@@ -0,0 +1,59 @@
+# Senior Research Playbook
+
+Reference for Phase 1 of the `junior-to-senior` skill: how the senior earns expertise the junior doesn't have. Two tracks, run in this order — code research grounds the review in this repo; web research grounds it in the present.
+
+## Track 1: Code research
+
+Goal: know what is *true here* before judging the plan against it. Prefer a context-isolated explore subagent for broad sweeps; bring back conclusions, not file dumps.
+
+Checklist per plan:
+
+1. **Versions.** Read the lockfile/manifest (`package-lock.json`, `poetry.lock`, `go.mod`, `Cargo.lock`, ...) for every dependency the plan touches. Record exact pinned versions. Any plan step that assumes an API must be checked against the pinned version's docs, not the latest.
+2. **Conventions.** Find 2-3 existing implementations of the closest analogous feature. How does this repo do routing, errors, config, tests, migrations? The plan either matches or justifies the break.
+3. **Prior decisions.** Search for ADRs, `docs/`, design notes, and revealing commit messages on the touched paths. A plan that re-litigates a settled decision without knowing it was settled is a blocker.
+4. **Real constraints.** Deploy target, build system, CI time budget, supported platforms, existing data volume and shape. These kill more plans than design taste does.
+5. **Blast radius.** What actually imports/calls the things the plan changes? The junior plan's scope estimate is a guess; the dependency graph is a fact.
+
+## Track 2: Web research
+
+Goal: find where the world moved after the training cutoff. Research the plan's *load-bearing decisions* (from Phase 1a), not every line — typically 3-7 searches total, not 30.
+
+### Query patterns
+
+For each load-bearing decision, run the subset that applies:
+
+- `<library> changelog` / `<library> release notes <current year>` — catch deprecations and new APIs since cutoff.
+- `<approach> vs <alternative> <current year>` — check whether the tradeoff has flipped.
+- `<pattern> deprecated` / `<pattern> considered harmful` — find published reversals.
+- `<technology> best practices <current year>` — only useful when followed to a primary source; the query itself attracts SEO spam, so treat listicle results as pointers, not evidence.
+- `<library> security advisory` / check the project's GitHub security tab — non-negotiable for auth, crypto, parsing, and anything touching user input.
+- `site:github.com <library> issues <feature>` — maintainer-stated direction and known footguns.
+
+Always pin the current year or "latest" into queries — undated queries return the same era the model was trained on, which defeats the point.
+
+### Source quality ranking
+
+1. Official documentation, changelogs, release notes, RFCs — cite freely.
+2. Maintainer blog posts, GitHub issues/discussions where maintainers state direction.
+3. Engineering postmortems and benchmarks from teams that ran the thing in production (with dates and numbers).
+4. Conference talks, well-known practitioner blogs — corroborate before citing for a blocker.
+5. SEO listicles, AI-generated tutorials, undated content — never evidence, at most a pointer to a real source.
+
+Every cited source gets a date check. A "best practices" article from before the relevant major version is training-data-era knowledge wearing a URL.
+
+### What you are looking for
+
+- **Deprecations** — the plan's approach is discouraged or removed in current versions.
+- **Supersessions** — a newer pattern/API has clearly won (look for the old way's own docs pointing at the new way — that's the strongest signal).
+- **Hard-won lessons** — advisories, postmortems, benchmarks that change the tradeoff the junior made on priors.
+- **Confirmations** — the junior's choice still holds. Record these too; they go in "What the junior got right".
+
+### When to stop
+
+- Each load-bearing decision has either one primary source confirming/refuting it, or two independent secondary sources agreeing.
+- Two consecutive searches on a decision return nothing newer than what you knew — the world likely didn't move; mark it confirmed-by-absence and move on.
+- Diminishing returns: research budget belongs on blockers and majors, not minors. If a finding would be minor either way, don't research it.
+
+### No web access
+
+Run Track 1 fully, skip Track 2, and tag every best-practice claim in the review `[training-data, unverified]`. Tell the user the review is grounded in the codebase but not refreshed against current SOTA, and name the decisions most likely to have shifted so they can spot-check.

skills/junior-to-senior/references/review-rubric.md

@@ -0,0 +1,67 @@
+# Senior Review Rubric
+
+Reference for Phase 2 (altitude diagnosis) and Phase 3 (adversarial review) of the `junior-to-senior` skill.
+
+## Altitude diagnostics
+
+Classify each section of the artifact independently. A plan is usually **mixed**: fogged on the hard parts, tunneled on the easy ones — because the junior wrote detail where it was comfortable and abstraction where it was not. That inversion (detail on easy parts, fog on hard parts) is itself a finding.
+
+### Fog tests (too vague)
+
+Run these against every component, step, or workstream the plan names. Each "no" is a finding.
+
+1. **Start-tomorrow test** — could a competent engineer begin this item tomorrow without making an architecture or product decision themselves? If they'd have to choose a library, design a schema, or define an API first, the plan didn't plan it.
+2. **Interface test** — does anything that crosses a boundary (function, service, queue, file, network) have its shape written down? Names of fields, not "the relevant data".
+3. **Failure test** — for each external interaction (network, disk, user input, third-party API), does the plan say what happens when it fails? "Handle errors" is not an answer.
+4. **Quantity test** — are load-bearing quantities stated? Expected row counts, payload sizes, request rates, latency budgets. "Should be fast" is fog.
+5. **Named-technology test** — is every "a cache / a queue / some auth layer" either named (with version) or explicitly listed as an open decision with the candidates?
+
+### Tunnel tests (too granular / missing vision)
+
+Run these against the artifact as a whole. Each "no" is a finding.
+
+1. **Audience test** — does the plan say who this is for and what they can do afterward that they couldn't before?
+2. **Success test** — is there an observable definition of success? A metric, a demo, a passing test suite, a user behavior — something checkable.
+3. **Non-goals test** — is anything explicitly out of scope? A plan with no non-goals has not been scoped, only described.
+4. **Alternative test** — does the plan say why this approach beat the obvious boring alternative? If no alternative was considered, the choice was a default, not a decision.
+5. **Sequencing test** — is there an ordering with a smallest useful version first, or is it a flat list of equally-weighted tasks?
+6. **Proportionality test** — does the detail land where the risk is? Twenty lines on a helper function and one line on the data migration means the plan is upside down.
+
+## Vague-word blacklist
+
+When these appear without immediate quantification or specification, challenge them with the concrete question they are hiding from:
+
+| Word | Hidden question |
+|---|---|
+| simple / straightforward | Simple compared to what? What did you not have to handle? |
+| scalable | To what number, on what axis, measured how? |
+| robust / resilient | Against which specific failures? What is the recovery path? |
+| handle gracefully | What exactly happens? Retry, drop, queue, surface to user? |
+| performant / fast | What latency/throughput budget, at what percentile? |
+| secure | Against which threat model? Who is the attacker? |
+| flexible / extensible | For which anticipated change? Flexibility has a cost — who pays it? |
+| later / eventually / for now | Is this a sequencing decision or an unowned risk? Who reopens it, triggered by what? |
+| etc. / and so on | The list was the work. Finish it. |
+| appropriate / as needed | By whose judgment, applied when? |
+| leverage / utilize | Usually decorating an undecided choice. Name the thing. |
+
+## Severity definitions
+
+- **Blocker** — the plan fails as written. Examples: targets an API the pinned dependency version doesn't have; contradicts an existing architectural decision in the repo without acknowledging it; omits a data migration that the change requires; relies on a pattern that has a published security advisory against it; an entire hard component is fog (fails the start-tomorrow test).
+- **Major** — the plan works but is meaningfully worse than the current state of the art or misfit to this repo. Examples: hand-rolls something a maintained, already-installed dependency provides; uses a pattern superseded since the training cutoff (with source); detail is inverted (proportionality failure); no rollback story for a hard-to-reverse step; success criteria exist but aren't observable.
+- **Minor** — polish. Naming, doc gaps, small idiom mismatches with the surrounding codebase, ordering tweaks that reduce risk but don't change the outcome.
+
+Calibration rules:
+
+- Severity reflects consequence, not effort-to-fix. A one-line version bump can be a blocker.
+- Every finding carries evidence (file:line, or source + date) and a concrete fix. A finding without a fix is a question — put it in "Open questions" instead.
+- Do not inflate. Three real blockers reads as a serious review; ten padded ones reads as noise and gets ignored.
+- Track "what the junior got right" with the same care as faults. The rewrite must preserve it, and the user needs to see the review is calibrated, not performatively hostile.
+
+## Adversarial discipline
+
+- **Steelman first.** Before attacking a choice, state the strongest case for it in one or two sentences. If you cannot, you do not understand it well enough to reject it.
+- **Attack the artifact, not the author.** Findings name the text's failure, not the agent's.
+- **Concede when beaten.** If research validates the junior's choice, say so and move on. An adversarial review that cannot return "this holds" is a ritual, not a review.
+- **One altitude per finding.** Do not bundle "this is vague" with "this library is outdated" — they have different fixes.
+- **No invented requirements.** If the review wants a constraint the user never stated (e.g., "must support 1M users"), that is an open question for the human, not a finding.