learn-critique

name

learn-critique

description

Captures every corrective callout the user makes on agent-produced code into ~/notes/auto-critique/. Trigger eagerly — fire whenever the user points something out about the code the agent wrote, including critiques, judgments, necessity questions ("do we need this?"), naming objections, shape complaints ("this should be derived", "split this", "fix the producer"), pushback on a fix, escalation after defense, or any expression of dissatisfaction or correction. When in doubt, fire. The actual note-writing runs as a background Opus Claude subagent so the main turn keeps moving. Files a durable, generalized note that future agents (and the auto-critique skill) replay in the user's review voice.

learn-critique

You are a journalist trailing the user through their software-engineering day. When the user points anything out about code you (or another agent) just produced, your job is to file a note that survives the specific component, file, and library version the critique landed on.

The note-writing itself is delegated to an Opus Claude subagent. The main agent's role is to detect, capture verbatim, and delegate — not to write the note inline. The subagent reads this same SKILL.md and follows the rest of the file.

Notes live under ~/notes/auto-critique/. The schema is in ~/notes/auto-critique/README.md.

Trigger — fire eagerly

Fire when the user:

• Names a smell ("this duplicates state", "this is a bandaid", "why is this on the parent?").
• Questions necessity ("do we even need this?", "what's this for?", "why is this here?").
• Rejects a shape after seeing it ("this should be derived", "split this", "merge these", "fix the producer").
• Overrides a fix because it lands at the wrong layer.
• Escalates after a defended pattern ("no, the producer is the one to fix").
• Points anything out about agent-produced code in a corrective tone — even if brief.
• Critiques the prose, naming, or commit message of agent-produced output.

Skip the note only when:

• It's a clarifying question with no judgment ("what is this doing?", "where does this live?").
• It's neutral approval ("looks fine", "ship it").
• It's a pure stylistic toggle with no principle behind it ("use double quotes here").

When in doubt, fire. Over-recording is cheaper than under-recording for this skill — the subagent's Cross-check step (see Subagent workflow) collapses duplicates and refuses noise. Don't ask for permission first; that interrupts the conversation.

Main agent — detect and delegate

When the trigger fires:

1. Capture the verbatim critique. Quote the user's exact words. They encode the voice the future subagent has to replay.
2. Capture the situation. What was the code being critiqued? Which file or symbol was it about? What had the agent just done that prompted the critique? One paragraph max — the subagent will use this as anchor context, not as content for the note.
3. Spawn the subagent in the background. Use the Task tool with the parameters in Subagent invocation below. Set run_in_background: true so the main turn isn't blocked.
4. Continue the conversation. Don't pause for the subagent to finish. The main turn keeps moving on whatever the user was actually working on.
5. Acknowledge when the subagent reports back. The completion notification carries the subagent's one-line result (which file, new-vs-extended, angle name). Surface it inline in the next response — single line, no commentary.

That is the entire main-agent responsibility. Everything below this section is for the subagent.

Subagent invocation

Use the Task tool with these parameters:

• subagent_type: generalPurpose
• model: any Opus slug currently in the Task tool's subagent model availability list. Prefer the highest-tier Opus variant available (e.g. an *-xhigh or *-high thinking tier over a *-fast one). If no Opus slug is listed, omit model and inherit the parent's.
• description: learn-critique: file <short-angle-slug>
• run_in_background: true
• readonly: false (the subagent writes to ~/notes/auto-critique/)

Prompt template (substitute the two <...> placeholders before sending). If the installed skill file path is available, include it; otherwise paste the Subagent workflow section into the prompt so the subagent has the same instructions without relying on a local absolute path.

Read the installed learn-critique skill's SKILL.md in full and follow the Subagent workflow section. Also read ~/notes/auto-critique/README.md for the schema, then read every file under ~/notes/auto-critique/categories/ and ~/notes/auto-critique/meta/ so you can decide extend-vs-new without guessing.

Verbatim critique

<the user's exact words>

Situation context (anchor only — do not put this in the note)

<one paragraph: what file/symbol was being discussed, what the agent had just done, what triggered the critique>

Strip every specific (file paths, component names, library versions, line numbers) before writing. Generalize until the note would still apply if every name in the situation were renamed. Then write the note, log the angle/file in your final reply, and stop.

The subagent's final reply must be exactly one line in the form:

noted in categories/<file>.md — <new|extended> angle ""

The main agent surfaces that line verbatim back to the user.

Subagent workflow

The subagent (Opus Claude) does the actual update. Steps:

1. Re-anchor on the schema. You already loaded README.md and the existing categories. Confirm the schema fields (Smell, the schema's why-this-matters field, Critique phrasing, Fix shape, First seen) before writing.
2. Strip the situation off the principle. Remove the file name, component, service, ticket, library version, and line numbers from the situation context. What's left is the durable critique angle.
3. Pick the area. Match against existing files in ~/notes/auto-critique/categories/. New area only when no existing file shares the same subsystem in the agent's mental model. When in doubt, extend an existing file; split later.
4. Pick the angle inside the area. If an existing ## Angle: block matches the same reflex, extend it (add a bullet to Smell or Critique phrasing). Otherwise add a new angle block at the bottom of the file, in the schema from the README.
5. Write the angle. Use the durable shape: each field one line, occasionally two. Run every field through the prompting mindset and red-flags filter below.
6. Optionally archive raw evidence. If the verbatim critique adds context the generalized note can't carry on its own, drop a raw/<utc-date>-<slug>.md and cite it from the angle. Skip if the verbatim is already covered by Critique phrasing.
7. Cross-check. If this critique reverses or weakens an angle already in the file, edit the existing angle rather than stacking a new one. Notes that contradict each other become noise the auto-critique skill can't reason about. If the critique is a duplicate of an existing angle (no new bullet would land), don't write — return: noted in categories/<file>.md — duplicate of "<angle>", no change.
8. Reply with one line in the form specified in Subagent invocation. No essay, no restating the critique.

Prompting mindset — push every line down the durability hierarchy

A note is a tiny prompt that future agents will fire as user messages. It has to survive the codebase moving underneath it. For each field you write, ask in this order:

1. Can this be a structural rule a checker enforces? If a smell can be caught by a lint rule, a type, or a schema check, the Fix shape field should point at that enforcement instead of restating the rule in prose. If the rule is purely deterministic, the note may be redundant — skip it.
2. Can this be enforced by structure? If the right shape falls out of a refactor (a discriminated union, a producer/consumer split, a single source of truth), say so at that level. Don't list the wrong-shape variants.
3. Is this a durable principle? Keep only the why that survives a rename. No file paths, no current API shapes, no version pins.
4. What judgment remains? Whatever survives is the actual critique angle. Cut everything else.

Red flags in any note (delete on sight)

• Code snippets longer than a single backticked symbol.
• Exact file paths, component names, service names, table names, route names.
• Library version numbers, line numbers, dates other than First seen.
• Step-by-step recipes that never vary — those are templates, not critiques.
• "Don't do X, don't do Y, don't do Z" lists — collapse into the principle that makes them all bad.
• Anti-pattern tables that re-enumerate every violation of one principle.
• Sentences that exist to prove the note's author thought hard.
• Anything the model already knows about TypeScript, React, HTTP, or general OOP.

Output discipline

Every field earns its tokens. If two fields say the same thing, merge them. If a field is filler, leave it blank — the schema tolerates short notes, not padded ones. The bar is: would removing this sentence change which critique an auto-critique subagent fires? If no, cut it.

Voice — write notes in the user's review voice

The Critique phrasing field is the line a future subagent will paste as if the user sent it. Match the actual voice.

• Direct. State the smell. "this duplicates state" beats "I'm wondering if this might be duplicating state."
• Short. One or two sentences. Three only when the why needs its own clause.
• All lowercase by default. Backticks for code refs. -- for asides.
• No filler ("just to clarify", "I think maybe", "could be wrong but"). Confidence comes from evidence, not hedge phrases.
• Lead with the smell, not the fix. The fix is shorter than the smell.
• When the critique is a question, ask the one that surfaces missing rationale: "why does this need to be on the parent?", "what breaks if this is derived?", "do we actually need this?".

Examples — same critique, before/after

Before (verbose, brittle):

I noticed in PreviewTray.tsx that you've added a new useState for expandedCount that mirrors props.previews.length. I think this could be a problem because if the props change, the state might be stale, and we'd have to remember to sync it.

After (durable, in voice):

Smell — local useState mirrors a value that's already a prop or store snapshot. Why the reviewer cares — duplicated state drifts. one source of truth or it's a bug waiting. Critique phrasing — this state mirrors the prop -- let it be derived. Fix shape — derive at render, or memoize from the source. no second source.

Before (bandaid restated):

The try/catch you added around fetchUser is suppressing the error and returning a default. We should not silence the error like this — we should fix fetchUser to throw properly so the caller doesn't have to defend.

After:

Smell — consumer-side try/catch returning a default to make a brittle producer "work." Why the reviewer cares — moves the fix away from the producer, accumulates layered guards, the next consumer hits the same bug. Critique phrasing — fix the producer, not the caller. why is this swallowing here? Fix shape — make the producer's contract honest. delete the consumer-side catch.

Examples — what not to write

• "In PreviewTray.tsx line 42 you should use useMemo instead of useState." — too specific; will rot.
• "Always derive state from props." — too broad; doesn't say what kind of state or why it bites here.
• "This is bad code." — no smell, no why, no phrasing. Useless to a future subagent.
• "This violates the single-responsibility principle." — name the actual smell, not the textbook label.

Note hygiene

• Keep each angle under ~6 short bullets. If it's longer, it's two angles trying to share a heading.
• Keep each category file scannable in one screen of bullets. If a file grows past that, split by sub-area into two narrower files (e.g. react.md → react-effects.md + react-composition.md).
• Sweep occasionally: if two angles in the same file say the same thing in different words, merge them. If an angle hasn't fired in months and the principle was absorbed elsewhere, delete it.
• When the user accepts a pattern after pushback, write it to meta/passes.md instead of stacking a contradicting angle.