feat(skills): import core skills from .agents catalog

- Add junior-to-senior with research playbook and review rubric
- Add fuck-slop with tell catalog and multi-register voice profiles
- Add interface-kit with design engineering, motion, and a11y references
- Add app-security with 4-pillar upload defense and hardening playbooks
- Add debugging-workflow with systematic root cause isolation
- Standardize all skills to 5-phase Skill Architect protocol
- Sync symlinks to OpenCode, Codex, and Claude Code
This commit is contained in:
vasily committed 2026-10-13 16:40:07 +08:00
1 parent 3a92d9fde5
commit 4fa17b8086
15 files changed
+3308

No files matched your search

+111
View File
@@ -0,0 +1,111 @@
---
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]
---
# 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 grounded in **this codebase as it actually exists** and **the state of the art today**, then tear down the plan 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.
- **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.
```
@@ -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.
@@ -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.