feat: refresh shared skills catalog
This commit is contained in:
vasily committed
1 parent
98bb35e6fb
commit
418792d1ec
49 files changed
+2273
-2390
No files matched your search
@@ -1,111 +1,26 @@
|
||||
---
|
||||
name: junior-to-senior
|
||||
description: >
|
||||
Adversarial senior-engineer review for agent-generated plans, designs, and architectures.
|
||||
Diagnoses altitude failures (fog vs tunnel) using live codebase research and current SOTA best practices, then rewrites into a scoped senior plan.
|
||||
Use when asked to review a plan, "senior review", "review this like a staff engineer", or before executing high-blast-radius plans.
|
||||
concerns: [system-one-balance]
|
||||
Review and improve a proposed plan or architecture when asked for a senior review, a staff-engineer review, or review of the plan.
|
||||
scope: global
|
||||
---
|
||||
|
||||
# Junior to Senior
|
||||
# Plan review
|
||||
|
||||
Assume the plan in front of you was written by a capable junior: fluent, confident, and trained on the past. Build a senior reviewer grounded in **this codebase as it actually exists** and **the state of the art today**, then tear down the plan and rebuild it.
|
||||
1. Identify the plan and its intended outcome. Inspect the relevant code, callers,
|
||||
dependency versions, and prior decisions. Cite file/line evidence for code claims.
|
||||
2. Find consequential gaps: vague goals, unstated contracts, unowned failure cases,
|
||||
scope mismatch, migration risk, or detail concentrated on easy parts.
|
||||
3. Verify load-bearing external assumptions against primary sources for the installed
|
||||
versions. Research only what can change a material decision; unavailable evidence
|
||||
stays unverified rather than becoming a blocker.
|
||||
4. Classify demonstrated defects, material improvements, and optional polish.
|
||||
Do not invent findings to look adversarial or copy the whole plan into the response.
|
||||
5. Provide concrete remedies. Rewrite the plan when requested or when a short revision
|
||||
makes the recommendations actionable; preserve sound choices and user intent.
|
||||
|
||||
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.
|
||||
- **Tunnel**: The plan dives into function signatures and file diffs without product vision, scoping boundaries, or justification for why this approach beats the boring alternative.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Setup and Protocols
|
||||
|
||||
1. Review governing reference playbooks:
|
||||
- [references/review-rubric.md](references/review-rubric.md) for altitude diagnostics, vague-phrase blacklists, and severity definitions.
|
||||
- [references/research-playbook.md](references/research-playbook.md) for codebase inspection queries, SOTA verification, and source ranking.
|
||||
2. Ground all critique in concrete evidence:
|
||||
- Codebase claims cite specific `file:line`.
|
||||
- SOTA claims cite primary documentation, release notes, or RFCs with dates.
|
||||
- If web research is unavailable, mark findings `[training-data, unverified]`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Ingest and Check
|
||||
|
||||
1. **Capture & Freeze the Artifact**:
|
||||
- Identify the target plan: a plan just produced in conversation, a pasted RFC/design doc, or a repository document.
|
||||
- Restate or quote the artifact in full before reviewing so the review targets a fixed specification.
|
||||
- If no plan exists, generate the junior draft or ask the user for their initial requirements first.
|
||||
2. **Altitude Diagnostic**:
|
||||
- Classify the artifact: **fog**, **tunnel**, or **mixed**.
|
||||
- Fog test: Can a competent engineer begin implementation tomorrow without making unstated product/architecture decisions?
|
||||
- Tunnel test: Does the plan state who this is for, what success means, what is out of scope, and why this beats the obvious alternative?
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Processing (Core Logic)
|
||||
|
||||
### Step 1: Construct the Senior Profile
|
||||
- **Domain Extraction**: Identify the 2–5 load-bearing technical domains the plan touches.
|
||||
- **Codebase Research**: Inspect repository lockfiles/manifests, actual dependency versions, existing conventions, data models, and constraints.
|
||||
- **SOTA Web Research**: Query current documentation and changelogs for deprecations, supersessions, or known postmortem failure modes.
|
||||
|
||||
### Step 2: Adversarial Critique
|
||||
- Challenge every vague term ("simple", "scalable", "robust", "handle gracefully").
|
||||
- Specify concrete data shapes, boundary contracts, migration paths, and rollback strategies.
|
||||
- Assign findings to three strict severity tiers:
|
||||
- **Blocker**: The plan fails as written or violates project invariants.
|
||||
- **Major**: Functions, but is significantly worse than current best practice or repo conventions.
|
||||
- **Minor**: Non-blocking improvements and ergonomic polish.
|
||||
- Acknowledge what the junior plan got right (credit preserved in rewrite).
|
||||
|
||||
### Step 3: Promote the Plan (v2)
|
||||
Rewrite the plan into senior form:
|
||||
1. **Goal & Non-Goals**: Crisp product intent and explicit out-of-scope boundaries.
|
||||
2. **Decisions & Rationale**: Each load-bearing choice with chosen option, version, rejected alternatives, and cited evidence.
|
||||
3. **Design at Right Altitude**: Exact contracts, schemas, and error boundaries for hard parts; coarse strokes for routine boilerplate.
|
||||
4. **Sequencing**: Measurable milestones with observable verification gates.
|
||||
5. **Risks & Rollback**: Blast-radius assessment and escape hatches.
|
||||
6. **Open Questions for Human**: Genuine product decisions requiring user judgment (the senior scopes; it does not fabricate product intent).
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: The System One Balance Pass
|
||||
|
||||
- **Augment, Don't Handcuff**:
|
||||
- Do NOT second-guess routine developer requests with unnecessary reviews.
|
||||
- If the user asks for immediate, direct execution ("implement this now", "fix bug"), proceed directly without forcing an unsolicited junior-to-senior review pass.
|
||||
- Never fabricate synthetic blockers just to appear rigorous; if a plan is solid, state "this plan holds" and proceed.
|
||||
- **Calibrated Advisories**:
|
||||
- Offer the promoted plan as an upgrade option; do not silently overwrite the user's intent.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Output Execution & Verification
|
||||
|
||||
Deliver the review and promoted plan formatted as two structured sections:
|
||||
|
||||
```markdown
|
||||
## Senior Review
|
||||
|
||||
**Altitude diagnosis:** fog | tunnel | mixed — [one-sentence justification]
|
||||
|
||||
### Blockers
|
||||
- [B1] Finding — evidence (file:line or source+date) — concrete fix.
|
||||
|
||||
### Major
|
||||
- [M1] Finding — evidence — concrete fix.
|
||||
|
||||
### Minor
|
||||
- [m1] Finding — polish recommendation.
|
||||
|
||||
### What the junior got right
|
||||
- [Preserved choices and good foundations]
|
||||
|
||||
---
|
||||
|
||||
## Promoted Plan (v2)
|
||||
[Goal, Decisions, Scoped Architecture, Milestones, Rollback, Open Questions]
|
||||
|
||||
## Delta Summary
|
||||
- 3–6 concise bullets explaining key upgrades from v1 to v2.
|
||||
```
|
||||
Use the [research playbook](references/research-playbook.md) and
|
||||
[rubric](references/review-rubric.md) only for relevant questions. A review can be
|
||||
brief when the plan is sound. Do not force this workflow onto a direct implementation
|
||||
request; focused risk inspection can be part of implementing it. Follow
|
||||
[shared workflow](../../protocols/workflow.md).
|
||||
@@ -4,7 +4,7 @@ Reference for Phase 1 of the `junior-to-senior` skill: how the senior earns expe
|
||||
|
||||
## 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.
|
||||
Goal: know what is *true here* before judging the plan against it. Use focused searches and return conclusions with evidence rather than file dumps. Delegate only when the task or repository instructions authorize it.
|
||||
|
||||
Checklist per plan:
|
||||
|
||||
@@ -29,7 +29,7 @@ For each load-bearing decision, run the subset that applies:
|
||||
- `<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.
|
||||
Query the installed version first; include dates when freshness matters. Latest-version guidance may not apply to the pinned dependency.
|
||||
|
||||
### Source quality ranking
|
||||
|
||||
@@ -51,7 +51,7 @@ Every cited source gets a date check. A "best practices" article from before the
|
||||
### 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.
|
||||
- If searches yield no useful evidence, mark the decision unverified and move on; absence of results is not confirmation.
|
||||
- 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
|
||||
|
||||
Reference in new issue
Block a user