skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/core/skills/doc-critique/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: doc-critique
+description: Review an existing document — ADR, design doc, runbook, exec summary, tech-comparison matrix, deck outline, decision log — and produce a structured critique against the same quality bars the skilldrop generators enforce. Categorizes findings by severity (blocker / major / minor / nit), points to the exact section/line, and suggests a concrete fix for each. Use when the user wants a second-pair-of-eyes review before sharing a doc, or has been handed someone else's artifact and wants to know what to push back on.
+---
+
+# doc-critique
+
+You help the user review an existing document with the same opinionated rubric the skilldrop generators use to *produce* them. The collection is otherwise asymmetric — every other skill creates artifacts; this one reviews them.
+
+## How to respond
+
+1. **Identify the doc type.** Ask if the user hasn't said. Match it to the closest skilldrop archetype:
+
+   | Doc type | Rubric file |
+   |---|---|
+   | ADR (MADR or Nygard) | [`rubrics/adr.md`](rubrics/adr.md) |
+   | Engineering design doc / RFC / tech proposal | [`rubrics/design-doc.md`](rubrics/design-doc.md) |
+   | Runbook / operational doc | [`rubrics/runbook.md`](rubrics/runbook.md) |
+   | Tech-comparison matrix / vendor selection | [`rubrics/tech-comparison.md`](rubrics/tech-comparison.md) |
+   | Exec summary / 1-pager | [`rubrics/exec-summary.md`](rubrics/exec-summary.md) |
+   | Slide deck or outline | [`rubrics/deck.md`](rubrics/deck.md) |
+   | Decision log / meeting notes | [`rubrics/decision-log.md`](rubrics/decision-log.md) |
+   | _Other / unsure_ | Use `rubrics/generic.md` and call out the type-mismatch |
+
+   For mixed/ambiguous docs (e.g. "a design doc that's also being used as a runbook"), pick the *primary* purpose and note the dual-use in the critique header.
+
+2. **Read the whole doc before commenting.** A finding that looks like a blocker on page 1 sometimes gets resolved by page 4 — don't fire critique at sections in isolation.
+
+3. **Apply the rubric, not your taste.** Each rubric has a fixed set of checks. Walk through them in order. If a check passes, note it pass-by-default (don't flood the output with green checkmarks); if it fails, write a finding.
+
+4. **Categorize every finding by severity:**
+
+   | Severity | Meaning |
+   |---|---|
+   | 🟥 **Blocker** | The doc can't ship without fixing this. A reviewer/exec/on-caller will be unable to act on the doc as-is. Example: ADR with no alternatives considered; runbook with no rollback command; exec summary missing The Ask. |
+   | 🟧 **Major** | The doc will ship and be used but a key decision is poorly supported / a section is missing or weak / a claim is unsupported. The doc loses credibility but doesn't fail outright. |
+   | 🟨 **Minor** | Style, ordering, redundancy, missing nice-to-haves. The doc works; this is the difference between "passable" and "good". |
+   | ⚪ **Nit** | Typo, formatting, terminology preference. Optional. |
+
+   When in doubt between two severities, downgrade. Inflated severity makes the critique unreadable.
+
+5. **For every finding, write three lines:**
+
+   - **Where:** quote 5–10 words verbatim from the doc, or cite the section heading + paragraph (e.g. *"§ Risks, ¶2"*). The user must be able to jump to the exact spot.
+   - **What's wrong:** name the failing rubric check in one sentence.
+   - **Suggested fix:** concrete. ✅ "Add a 'why-not' to the DynamoDB option (one sentence — likely 'cross-table transactions not supported')." — ❌ "Improve the alternatives section."
+
+6. **Open with a verdict, not a critique.** The first thing the user reads is a one-line verdict + a 3-sentence executive summary:
+
+   ```
+   Verdict: SHIP WITH CHANGES — 1 blocker, 4 major, 6 minor.
+
+   The decision and trade-offs are clear, but two of the four "considered options" are described without a why-not, which breaks the ADR's audit value. The status field is set to "Accepted" but no deciders are listed, which the team's ADR policy requires. Minor issues are mostly tone (hedging language) and one out-of-order section.
+   ```
+
+   Verdicts are one of: `SHIP IT`, `SHIP WITH CHANGES`, `MAJOR REWRITE`, `WRONG ARTIFACT`. The last one is for when the doc is the wrong *kind* — e.g. user wrote a design doc but the situation needs an ADR.
+
+7. **Output structure** — use [`templates/critique.md`](templates/critique.md):
+
+   ```markdown
+   # Critique: {doc title}
+   _Type: {ADR | design-doc | …} · Reviewed: {YYYY-MM-DD} · Rubric: {rubric file}_
+
+   ## Verdict
+   {one-liner} — {N} blocker, {N} major, {N} minor, {N} nit
+   {3-sentence summary}
+
+   ## Findings
+
+   ### 🟥 Blockers
+   1. **Where:** *"…"* (§ Section, ¶N)
+      **What:** {one sentence}
+      **Fix:** {one sentence, concrete}
+
+   ### 🟧 Major
+   …
+
+   ### 🟨 Minor
+   …
+
+   ### ⚪ Nits
+   …
+
+   ## What's working
+   - {2–4 specific things the doc does well — not flattery, real reusable strengths}
+   ```
+
+8. **End with "what's working"**, not more criticism. Two reasons: (a) the user often wants to know which parts to *keep* during a rewrite, and (b) finishing on weak points trains the user to dread review rather than ask for it.
+
+## Quality bar
+
+- **Severity is calibrated.** If your output has more blockers than major issues, you're inflating. Reread and demote.
+- **Findings are local, not global.** "The whole tone is off" is not a finding; "§ TL;DR uses 'innovative' and 'leverage' — replace with concrete verbs" is.
+- **Fixes are paste-able where possible.** If the fix is "add an X section", show what the X section should contain in 2–3 bullets.
+- **Don't review the topic, review the doc.** It's not your job to redebate whether Postgres beats DynamoDB — only whether the doc made its case competently.
+- **Quote the doc, don't paraphrase.** Just like `decision-log`, the quoted snippet is the audit trail that proves you read the actual words.
+
+## When to use this skill
+
+- ✅ Before publishing an ADR, design doc, or runbook — author wants a sanity check.
+- ✅ When the user is asked to review someone else's doc and wants a structured frame.
+- ✅ As a checkpoint after one of the generator skills, before the user shares the artifact externally.
+- ✅ When the user says "is this any good?" with a doc attached.
+
+## When NOT to use this skill
+
+- ❌ For evaluating the *underlying decision* (is Postgres the right choice?). That's a tech-debate, not a doc review — use `tech-comparison-matrix` instead.
+- ❌ For grammar / spelling pass on a doc that's otherwise solid. Use a normal editor.
+- ❌ For evaluating code. This skill reviews *documents*; for code review, the user has other tools.
+- ❌ For generating the doc. If the user wants a draft, that's the matching generator skill.
+
+## Anti-patterns to avoid
+
+- ❌ Severity inflation. If everything is a blocker, nothing is.
+- ❌ Vague findings ("clarify the proposal section"). Always quote and always suggest a fix.
+- ❌ Critiquing the *author's voice* — comment on the doc's *fitness for purpose*, not personality.
+- ❌ Restating the rubric ("ADRs should have alternatives"). The finding is about *this* doc's failure to meet it.
+- ❌ Skipping "What's working." The user came for honesty in both directions.
+- ❌ Re-debating the underlying decision. The doc could make a great case for the wrong choice — and that's still a "ship it" from the doc's perspective.

skilldrop_cli/data/packs/core/skills/doc-critique/evals/eval_queries.json

@@ -0,0 +1,38 @@
+[
+  {
+    "query": "Critique this design doc before I share it",
+    "should_trigger": true
+  },
+  {
+    "query": "Review this ADR and tell me where it's weak",
+    "should_trigger": true
+  },
+  {
+    "query": "Is this runbook actually good? Give me a structured critique",
+    "should_trigger": true
+  },
+  {
+    "query": "Score this exec summary against a quality bar",
+    "should_trigger": true
+  },
+  {
+    "query": "Review my document and give me severity-tagged findings with fixes",
+    "should_trigger": true
+  },
+  {
+    "query": "Review this pull request for bugs",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a new ADR for this decision",
+    "should_trigger": false
+  },
+  {
+    "query": "Get five senior personas to deliberate whether we should do this",
+    "should_trigger": false
+  },
+  {
+    "query": "Summarize this document for executives",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/core/skills/doc-critique/evals/evals.json

@@ -0,0 +1,17 @@
+{
+  "skill_name": "doc-critique",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Critique this design doc before I circulate it to the team. [design doc: a TL;DR full of adjectives, an approach section that says 'industry standard', no SLOs, and a one-line rollout plan]",
+      "assertions": [
+        "Every finding quotes the document verbatim rather than paraphrasing it — the quoted snippet is the audit trail",
+        "Findings are local and anchored to a section, not global judgments like 'the tone is off'",
+        "Severity is calibrated — blockers do not outnumber majors",
+        "Fixes are paste-able: when the fix is 'add a section', the critique shows what that section should contain",
+        "The critique reviews whether the doc made its case, and does not re-debate the underlying technical topic",
+        "The document archetype is identified and the critique is run against that archetype's quality bar"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/core/skills/doc-critique/examples/design-doc-critique.md

@@ -0,0 +1,34 @@
+# Worked example — critique of a design-doc excerpt
+
+Input → output oracle for `doc-critique`. Shows local, doc-quoting findings with
+paste-able fixes — reviewing whether the doc *made its case*, not re-debating the topic.
+
+## Input (excerpt of a design doc under review)
+
+> ## TL;DR
+> We will build an innovative, scalable notification service to leverage our
+> existing infrastructure and deliver best-in-class user engagement.
+>
+> ## Approach
+> The service consumes events and sends notifications. It will be highly
+> available and performant. We considered several options and chose a
+> queue-based design because it is the industry standard.
+>
+> ## Rollout
+> We will roll it out to all users.
+
+## Output (the critique)
+
+**Verdict: not ready to circulate — 1 blocker, 2 major, 1 minor.** The doc asserts conclusions it never earns; a reader can't tell what's being built or why this shape.
+
+🟥 **Blocker — the decision has no rationale (§ Approach).** Quoted: *"chose a queue-based design because it is the industry standard."* "Industry standard" is not a reason; it hides the actual tradeoff. *Fix:* replace with the decision's real driver — e.g. "chose a queue so a downstream outage buffers events instead of dropping them; the alternative (synchronous fan-out) loses notifications when a provider is down." Name the alternative and why it lost.
+
+🟧 **Major — TL;DR is adjectives, not content (§ TL;DR).** Quoted: *"innovative, scalable … leverage … best-in-class user engagement."* Five value-words, zero facts — a reader learns nothing about scope. *Fix:* state what it does and the one number that matters: "A queue-backed service that delivers email/push notifications from domain events, targeting < 5s p95 delivery for 1M events/day."
+
+🟧 **Major — unfalsifiable quality claims (§ Approach).** Quoted: *"highly available and performant."* No SLO, so nothing can be reviewed or later checked. *Fix:* commit numbers — availability target (e.g. 99.9%), p95 latency, throughput — or move them to an explicit "Open questions" list if unknown.
+
+🟨 **Minor — rollout has no stages or guardrail (§ Rollout).** Quoted: *"roll it out to all users."* No canary, no rollback trigger. *Fix:* a 2–3 line staged plan (1% → 10% → 100%) and the metric that halts it (delivery-failure rate > X%).
+
+## Why this passes the quality bar
+
+Severity is calibrated (one blocker). Every finding is **local** and **quotes the doc verbatim** (the audit trail that it was actually read), the fixes are paste-able, and it critiques the *doc's* case-making — it does not re-argue whether a queue is the right architecture.

skilldrop_cli/data/packs/core/skills/doc-critique/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "doc-critique",
+  "version": "0.1.0",
+  "description": "Review an existing document — ADR, design doc, runbook, exec summary, tech-comparison matrix, deck outline, decision log — and produce a structured critique against the same quality bars the skilldrop generators enforce. Categorizes findings by severity (blocker / major / minor / nit), points to the exact section/line, and suggests a concrete fix for each. Use when the user wants a second-pair-of-eyes review before sharing a doc, or has been handed someone else's artifact and wants to know what to push back on.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["decision-log", "tech-comparison-matrix"],
+  "tags": ["review", "critique", "quality", "rubric", "feedback"],
+  "model": { "tier": "heavy", "rationale": "Adversarial doc review against rubrics. The value is catching what a fast pass misses. Never downgrade." }
+}

skilldrop_cli/data/packs/core/skills/doc-critique/rubrics/adr.md

@@ -0,0 +1,36 @@
+# Rubric: ADR
+
+Mirrors `adr-generator`'s quality bar.
+
+## Blockers
+- **Title is a noun phrase**, not a verb phrase or a question.
+  ❌ *"Decide what database to use"* / *"Database decision"* ✅ *"Use Postgres as the primary OLTP datastore"*
+- **At least 2 considered options.** If only one option appears, it's not a decision; it's a plan. Demand alternatives or downgrade the artifact to a design note.
+- **Status is one of:** `Proposed | Accepted | Deprecated | Superseded by ADR-NNNN`. Anything else (e.g. `Final`, `Done`, `WIP`) breaks search/automation.
+- **Decision is stated explicitly.** A reader must be able to extract the decision in one sentence without parsing the trade-offs first.
+- **Consequences include trade-offs, not just upsides.** A consequences section with no ❌/⚠️ items hasn't engaged with the decision honestly.
+
+## Major
+- **Status of "Accepted" requires deciders listed.** Otherwise the audit trail is broken.
+- **Every considered option has a why-not.** "We didn't pick DynamoDB" is not enough — it must say *why*.
+- **Decision drivers tie to the chosen option's rationale.** If the drivers list QPS and cost, but the chosen option's rationale is "team familiarity", drivers are decorative.
+- **Numbered correctly.** Sequential, zero-padded (`0007-`, not `7-` or `007-`).
+- **MADR vs Nygard fit.** Heavy decisions in Nygard's 4-section format lose nuance; trivial decisions in MADR look bureaucratic. Note when the format doesn't fit the decision's weight.
+
+## Minor
+- **Date present and absolute** (`YYYY-MM-DD`, not "Q3 2024").
+- **Filename matches slug:** `NNNN-kebab-case-title.md`.
+- **Tags / context links** present if other ADRs supersede or relate to this one.
+- **Active voice in the decision sentence.**
+- **No "TBD"** in published ADRs — move to a follow-up.
+
+## Nits
+- Markdown formatting (headings, code-fence languages).
+- Inconsistent verb tense (past vs present) — pick one.
+- Bullet style consistency.
+
+## What's working — look for
+- Decision drivers tied directly to options' pros/cons.
+- Honest "we picked the worse-on-paper option because X" — these are gold.
+- Cross-links to the related design doc / spike / experiment.
+- Real downsides in consequences, not throat-clearing.

skilldrop_cli/data/packs/core/skills/doc-critique/rubrics/decision-log.md

@@ -0,0 +1,39 @@
+# Rubric: Decision Log
+
+Mirrors `decision-log`'s quality bar. The test: can a reader who *didn't attend* act on this log without going back to the source?
+
+## Blockers
+- **Decisions and action items are in separate tables.** Mixing them defeats the audit trail.
+- **Every action item has an owner (named person).** Unowned actions don't get done — they must at minimum be flagged as `unowned`, not pretended-owned.
+- **Dates are absolute.** "Friday" / "next week" / "EOQ" without a `YYYY-MM-DD` conversion blocks tracking.
+- **Source column present** with a verbatim 5–10 word snippet for every row. Without it, hallucination is undetectable.
+
+## Major
+- **Decisions are decisions, not opinions.** "I think we should X" is not a decision — only group-acknowledged conclusions count.
+- **Active voice in actions.** ❌ *"ADR-0007 to be sent to legal"* ✅ *"Send ADR-0007 to legal"*
+- **Risks-raised section present** when the source has any. Risks are the most likely follow-up agenda item.
+- **Open questions have a candidate owner** to answer (even if "needs assignment").
+- **Gaps section present.** Action items without owners or dates, decisions without rationale — all surfaced explicitly.
+
+## Minor
+- **Attendees listed.** Useful for "who else needs to be looped in on this follow-up?"
+- **Meeting / thread date present** at the top.
+- **Today's date used for relative conversions** — and noted in the doc.
+- **Tables consistent** — same columns across all four sections.
+
+## Nits
+- Numbering across tables (`#` column).
+- Table alignment / formatting.
+- Name disambiguation when two people share a first name.
+
+## Anti-patterns to flag (always major)
+- "AOB" or generic catch-all entries with no specifics.
+- Capturing every utterance — log is bloated and load-bearing items get lost.
+- Hallucinated attendees, dates, or rationale not present in the source.
+- Mixing the meeting's *discussion* (verbatim points) with its *outputs* (decisions/actions).
+
+## What's working — look for
+- Verbatim source quotes that prove the extraction is faithful.
+- Unowned items flagged rather than silently assigned.
+- Relative dates converted with `(implied)` markers.
+- Risks raised in the meeting that aren't in any decision — saved for follow-up.

skilldrop_cli/data/packs/core/skills/doc-critique/rubrics/deck.md

@@ -0,0 +1,45 @@
+# Rubric: Slide Deck / Outline
+
+Mirrors `slide-outliner` + `deck-builder` quality bars. Apply to either a finished deck (read titles + speaker notes) or an outline.
+
+## Blockers
+- **Audience is explicit or obvious from the deck.** Same content for execs vs engineers is a different deck — if you can't tell which one this is, that's the blocker.
+- **Title slide isn't blank.** Real title + subtitle + presenter + date.
+- **No surprise endings.** First and last slides match in style; the deck reads as one document, not two stitched together.
+- **No fake numbers.** If a `big_number` slide reads "$24M ARR at risk" and that number isn't in the source brief, it's invented. Demand evidence or removal.
+
+## Major
+- **Slide count matches audience.** Exec deck >12 slides = major. Technical review <8 = thin. See `audience-profile`.
+- **Bullet density matches audience.**
+  - Exec: max 3 bullets, max ~8 words each.
+  - Technical: up to 6 bullets if content really needs them.
+  - More than that ⇒ flag.
+- **Speaker notes exist for every slide.** Even one sentence. Without them the reviewer/co-presenter can't follow what's *between* the bullets.
+- **Section dividers used sparingly.** At most one every 4–5 content slides.
+- **Story arc visible from titles alone.** Read just the slide titles in order — do they tell the story? If not, the deck is a list, not a narrative.
+- **Layout variety where it earns its keep.** `content` slide after `content` slide after `content` slide is unread by slide 4. Big numbers, quotes, two-column should appear when the content suits them — not as decoration.
+
+## Minor
+- **Palette is consistent.** No surprise colors that aren't in the palette.
+- **Contrast is readable.** Light grey text on white = always flag.
+- **Title style is consistent** (assertion / descriptive / outcome — pick one per deck).
+- **No more than ~20 slides** for any audience. >20 ⇒ deck isn't the right format.
+- **Ask slide present** (the closing slide with the explicit request — "Approve the $X budget by Y").
+
+## Nits
+- Punctuation consistency in titles (all sentence case vs all title case).
+- Footer / page numbers consistent.
+- Image alt text / accessibility (rare but worth flagging for board / regulated audiences).
+
+## Anti-patterns to flag (always major)
+- "Agenda" slide as slide 2 of a 6-slide exec deck. The deck *is* the agenda.
+- Repeated bullets across slides (says the same thing 3 different ways).
+- A deck that opens with "About us" before "the Ask" — for any audience that didn't request a company backgrounder.
+- Animations or transitions referenced in notes — flag as a craft smell unless explicitly justified.
+
+## What's working — look for
+- A `big_number` slide using a real number from the source.
+- A `quote` slide where the quote actually changes the reader's mind.
+- A title that's an assertion ("X will cost $Y if we don't act") rather than a label ("X overview").
+- Speaker notes that say *what to skip if running short on time*.
+- A clear Ask in the final slide.

skilldrop_cli/data/packs/core/skills/doc-critique/rubrics/design-doc.md

@@ -0,0 +1,42 @@
+# Rubric: Design Doc
+
+Mirrors `design-doc`'s quality bar.
+
+## Blockers
+- **"Why now" is present.** No forcing function = a design doc that can be postponed indefinitely. Refuse to ship.
+- **Goals and non-goals both exist.** A missing non-goals section means scope will eat the project.
+- **Proposal is the longest section.** If "Background" or "Alternatives" is longer than "Proposal", the doc has buried the lede.
+- **At least 2 alternatives** each with a *why-not*. "We didn't pick X" with no reason is not an alternative.
+- **Risks have mitigations.** A bare risks list is anxiety, not engineering.
+
+## Major
+- **Non-goals are real, not throat-clearing.** ❌ *"We're not solving world hunger"* ✅ *"v1 will not migrate existing customers."*
+- **Rollout criteria are concrete.** ❌ *"We'll monitor closely"* ✅ *"Roll forward to 100% if p99 < 80ms for 48h after 10% rollout."*
+- **TL;DR is self-contained.** A reader who stops after the TL;DR should know what's being proposed and the recommendation.
+- **Diagrams where structural.** Long prose for things a flowchart would convey in 10 seconds is a smell.
+- **Open questions name owners.** "We need to figure out X" with no one tagged means X won't get figured out.
+
+## Minor
+- **Length: 2–5 rendered pages.** Longer means the doc is reference material in disguise, or solving two problems at once.
+- **Status field present and current** (`Draft | In Review | Approved`).
+- **Author + date** at the top.
+- **Active voice when assigning ownership** ("Team Foo will own X", not "X will be owned").
+- **Inline links to ADRs / runbooks / dashboards** that the doc references.
+
+## Nits
+- Heading hierarchy consistency.
+- Code-block language tags.
+- Acronyms expanded on first use.
+
+## Anti-patterns to flag (always major)
+- Implementation detail before problem statement.
+- "Future work" section that doubles the doc length with hypotheticals.
+- Passive voice masking ownership ("it will be deployed" — by whom?).
+- "We already know what to do" alternatives section that skips the analysis.
+
+## What's working — look for
+- A genuine non-goal that constrains scope.
+- A concrete rollback criterion with a number.
+- An "Open question" with a named owner.
+- Diagrams that *replace* prose rather than decorate it.
+- Honest trade-offs in the recommended approach (not just upsides).

skilldrop_cli/data/packs/core/skills/doc-critique/rubrics/exec-summary.md

@@ -0,0 +1,41 @@
+# Rubric: Exec Summary / 1-Pager
+
+Mirrors `exec-summary`'s quality bar. The test: can a VP read this in 60 seconds between meetings and either approve, push back, or ask exactly one clarifying question?
+
+## Blockers
+- **The Ask is the first thing.** If "What we need from you" is at the bottom of page 2, the doc is failing its only job.
+- **TL;DR is self-contained.** A reader who stops after the TL;DR must be able to decide. No "see below".
+- **One page.** ~300–400 words rendered including headings. If it's two pages, it's not an exec summary.
+- **Plain language in the first paragraph.** Any unrecognized jargon in the first 100 words blocks comprehension.
+
+## Major
+- **Business impact is quantified or explicitly "directional".** Made-up precision is worse than honest qualification.
+- **Risks are project-specific.** Generic risks ("scope creep", "team turnover") prove nothing was thought through.
+- **What we need from you is concrete.** ❌ *"Alignment"* ✅ *"Sign off on the $1.2M budget by Friday."*
+- **Cost & timeline are numbers, not adjectives.** Even rough numbers ("$200–400k, 5–7 months") beat "modest investment, short timeframe."
+- **Audience-fit.** A 1-pager for the CFO leads with cost; one for the CTO leads with technical risk; one for the board leads with strategic context. Wrong leading section ⇒ major finding.
+
+## Minor
+- **Active voice.** "You'll need to approve…" beats "Approval will be required…".
+- **Adjectives stripped.** "Robust", "scalable", "innovative", "leverage" — flag each occurrence as a candidate replacement.
+- **History the audience already knows is cut.** "As you know, in 2022 we launched…" is calorie-free.
+- **Section ordering follows the template** (Ask → TL;DR → Impact → Cost/Timeline → Risks → Need-from-you). Deviation needs a reason.
+
+## Nits
+- Bullet density (4–5 max per section in a 1-pager).
+- Numbers formatted consistently ($1.2M vs $1,200,000 — pick one).
+- No trailing whitespace / orphan headings.
+
+## Anti-patterns to flag (always major)
+- Burying the recommendation on page 2.
+- Listing technical wins ("reduced p99 by 40ms") with no business translation.
+- Asking the exec to "review the full design doc for details" without specifying which sections.
+- "Next steps: align with stakeholders" — empty-calorie ask. Demand the *actual* action.
+- Hedging language ("we believe", "in many cases", "potentially") in the recommendation sentence.
+
+## What's working — look for
+- A quantified Ask that's calibrated (number + timeframe + currency).
+- A project-specific risk with a real mitigation.
+- A line that translates a technical metric into a business outcome.
+- Audience-appropriate framing (CFO leads with $, board leads with strategy).
+- The doc visibly cuts material that would belong in the design doc.

skilldrop_cli/data/packs/core/skills/doc-critique/rubrics/generic.md

@@ -0,0 +1,40 @@
+# Rubric: Generic
+
+Use this when the doc doesn't cleanly match any of the skilldrop archetypes (ADR, design doc, runbook, exec summary, tech-comparison, deck, decision log). Also use when the doc is a *blend* (e.g. "a design doc that's also being used as a runbook" — pick one as primary and flag the dual-use).
+
+The first finding is usually whether the doc is the **wrong artifact for the job**.
+
+## Blockers
+- **Purpose is clear in the first paragraph.** The reader must know what kind of doc this is and what it's for.
+- **The doc has a single audience.** Trying to address "execs + engineers + customers" in one doc almost always fails one of them.
+- **The doc makes a claim or a request.** If after reading it the user doesn't know what action is being requested or what conclusion was reached, the doc has no point of view.
+- **No `TBD` / `<insert later>` left in a doc being shared.**
+
+## Major
+- **Section ordering matches the reader's path.** What does a reader who skims need first? That's slide 1, paragraph 1, section 1.
+- **Claims have evidence.** Numbers, quotes, links — not assertions in a vacuum.
+- **The doc is the right length** for its purpose. A 12-page doc when a 1-pager would do, or vice versa.
+- **Wrong artifact:** the situation needed an ADR but the user wrote a design doc, or vice versa. Verdict: `WRONG ARTIFACT` + recommend the correct skilldrop skill.
+
+## Minor
+- **Title is descriptive** — a reader scanning a doc index can tell what's inside.
+- **Last-updated date present.**
+- **Owners / authors named.**
+- **Cross-links** to related docs (ADRs, design docs, dashboards).
+
+## Nits
+- Heading hierarchy.
+- Tense consistency.
+- Code-block language tags.
+
+## Anti-patterns to flag (always major)
+- Burying the recommendation / conclusion.
+- Sections of "background" longer than the conclusion.
+- Hedging language masking a real position ("we believe", "it could be argued", "potentially").
+- Footnotes that contradict the body.
+
+## What's working — look for
+- A clear point of view stated up front.
+- Section ordering that respects the reader's path.
+- Honest acknowledgement of what the doc *doesn't* cover.
+- Cross-links to related artifacts (no doc is an island).

skilldrop_cli/data/packs/core/skills/doc-critique/rubrics/runbook.md

@@ -0,0 +1,42 @@
+# Rubric: Runbook
+
+Mirrors `runbook-generator`'s quality bar — and the harshest test: would a sleep-deprived on-caller at 3am succeed using this?
+
+## Blockers
+- **Service identity is unambiguous** — name + one-line purpose. No "the service" without naming it.
+- **Owner team listed (role-based, not individuals).** Individual names go stale; rotations/teams don't.
+- **Escalation chain is present.** "Page primary, then secondary, then manager" with the rotation name.
+- **Rollback is one command or three steps max.** If rollback is a 12-step procedure, link to a script — and that script must exist.
+- **Every listed alert has a response.** A "common alerts" section that doesn't cover all alerts is worse than no section.
+- **No `TBD` in a published runbook.** Move TBDs to an explicit "known gaps" section.
+
+## Major
+- **The "common 5" failure modes are covered.** Each with: how to recognize, immediate mitigation, root-cause first step, escalation criterion.
+- **Commands are paste-able.** ❌ *"Restart the pods"* ✅ *`kubectl rollout restart deployment/payments-api -n payments`*
+- **Dashboards / alerts linked, not inlined.** They go stale faster than the runbook.
+- **Deploy and rollback are near the top**, not buried after architecture context.
+- **Dependencies named** (upstream and downstream services + their on-call contacts).
+
+## Minor
+- **Order matches the 3am workflow:** active incidents → deploy/rollback → common failures → deeper context.
+- **SLOs listed** with a link to where they're enforced.
+- **Change calendar / freeze policy** noted if applicable.
+- **Last-reviewed date** at the top.
+
+## Nits
+- Consistent command formatting (always in code blocks).
+- Consistent naming for environments (`prod` not "production" in one place and "PROD" elsewhere).
+
+## Anti-patterns to flag (always major)
+- Architecture diagrams *inside* the runbook (they go stale — link to the design doc).
+- Long backstory before operational commands.
+- "Page X if you're not sure" without saying *what X knows that you don't*.
+- Listing every Prometheus metric. Pick the 5–10 that predict outages.
+- Generic "check the logs" with no log query or dashboard.
+
+## What's working — look for
+- Failure modes that name the alert that fires for them.
+- Rollback that's literally one command.
+- Concrete escalation criteria ("page secondary if not acknowledged in 10 min").
+- Dependency table with on-call contacts for each.
+- An honest "known gaps" section.

skilldrop_cli/data/packs/core/skills/doc-critique/rubrics/tech-comparison.md

@@ -0,0 +1,40 @@
+# Rubric: Tech-Comparison Matrix
+
+Mirrors `tech-comparison-matrix`'s quality bar.
+
+## Blockers
+- **The question is one sentence and answerable.** ❌ *"Database options"* ✅ *"Pick a primary OLTP datastore for the new checkout service."*
+- **≥2 candidates.** A "comparison" with one candidate is a proposal, not a comparison.
+- **Criteria are listed before scoring.** Otherwise the matrix is just opinion in a table.
+- **Weights are explicit** (even if equal) — otherwise the recommendation is unaccountable.
+- **A recommendation is made.** A matrix that ends with "it depends" without a follow-up framing is unfinished.
+
+## Major
+- **Each criterion has a 1-line definition** of what "good" looks like, so scores are comparable.
+- **Scores are justified.** A score of 5/5 with no rationale is decoration. Each cell needs at least a one-line why.
+- **Constraints / non-negotiables called out** *before* scoring — otherwise low-weighted criteria can mask hard disqualifiers.
+- **The recommendation cites which weighted scores carry it,** not "X is the best".
+- **Bias acknowledged.** If the team already prefers X, the doc should say so and explain why the matrix didn't just rubber-stamp that preference.
+
+## Minor
+- **Workload profile section** — read/write ratio, scale targets, consistency requirements. Without this, criteria like "scalability" are unanchored.
+- **Cost dimension** quantified (or marked qualitative if vendor pricing is opaque).
+- **Time horizon** stated ("12 months" vs "5 years" changes which scores matter).
+- **Operability score considered**, not just feature parity.
+
+## Nits
+- Table formatting; column alignment.
+- Consistent score scale (1–5 vs 0–10 — pick one).
+- Vendor / project names spelled correctly and consistently.
+
+## Anti-patterns to flag (always major)
+- Cherry-picked criteria that obviously favour one candidate (e.g. listing 5 features that only Vendor A has).
+- Mixing weights and scores into one number (multiplied) without showing both — strips reviewers of the ability to disagree on weighting.
+- Footnotes that quietly override the matrix's conclusion ("we picked X anyway because…") — that's a real reason, surface it.
+- Score for "community / ecosystem" without any concrete metric (GitHub stars, Stack Overflow questions, vendor revenue).
+
+## What's working — look for
+- A non-winner scoring high on a single load-bearing criterion — that's honesty.
+- Weights that visibly shifted the outcome (small change in weighting changes the recommendation — and the doc says so).
+- A "what would change our mind" section.
+- Explicit acknowledgement that the team's existing skill profile influenced one criterion.

skilldrop_cli/data/packs/core/skills/doc-critique/templates/critique.md

@@ -0,0 +1,49 @@
+# Critique: {Doc title}
+
+_Type: {ADR | design-doc | runbook | tech-comparison | exec-summary | deck | decision-log | generic}_
+_Reviewed: {YYYY-MM-DD}_
+_Rubric: `rubrics/{type}.md`_
+
+## Verdict
+**{SHIP IT | SHIP WITH CHANGES | MAJOR REWRITE | WRONG ARTIFACT}** — {N} blocker · {N} major · {N} minor · {N} nit
+
+{3-sentence summary. Lead with the most load-bearing finding. End with the headline strength so the user knows what to preserve.}
+
+---
+
+## Findings
+
+### 🟥 Blockers
+1. **Where:** *"{verbatim 5–10 word quote from the doc}"* (§ {Section}, ¶{N})
+   **What:** {one sentence — which rubric check fails}
+   **Fix:** {one sentence, concrete and paste-able where possible}
+
+2. **Where:** *"{…}"* (§ {Section})
+   **What:** {…}
+   **Fix:** {…}
+
+### 🟧 Major
+1. **Where:** *"{…}"* (§ {Section}, ¶{N})
+   **What:** {…}
+   **Fix:** {…}
+
+### 🟨 Minor
+1. **Where:** *"{…}"* (§ {Section})
+   **What:** {…}
+   **Fix:** {…}
+
+### ⚪ Nits
+- *"{quote}"* — {one-line note}
+
+---
+
+## What's working
+- **{Strength 1}** — *"{quote}"* (§ {Section}). {Why this is a real strength worth preserving in any rewrite.}
+- **{Strength 2}** — *"{quote}"*. {…}
+- **{Strength 3}** — *"{quote}"*. {…}
+
+---
+
+## Next steps
+- {Suggested order: fix blockers → ship draft → address major in a follow-up pass.}
+- {If verdict is `WRONG ARTIFACT`, name the right skilldrop skill to invoke.}