agentleFS
abhaylaabhayla/claude-best-practices/.claude/skills/prompt-auto-enhance/SKILL.md

prompt-auto-enhance

Skill9 starsChanged 7 months agoMITView on GitHub

Diagnose and strengthen non-trivial prompts by mapping weak spots to fixes and rewriting before execution — with visible step transcript, final prompt preview, before/after comparison, and an optional one-line skill hint when the strengthened prompt clearly fits a workflow other than direct execution. Also handles resource CRUD batch approval flow, delegation routing, and web search decisions. Invoked by the prompt-auto-enhance rule when resource changes are detected, or explicitly via /prompt-auto-enhance for manual enhancement.

The file

Show its rules and text

We split this skill into the rules it gives an agent

42 rules. About 0 are common, 32 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈32

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Load-bearing test: if the misheard word changes WHAT gets built (two plausible readings diverge materially), do NOT guess — route it to the …

    line 93
  2. Distinctive:

    Every score in [1.0, 10.0] now maps to exactly one grade.

    line 138
  3. Distinctive:

    No quote → no override; "could be better" never qualifies.

    line 171
  4. Very specific:

    Policy: never skip MISSING_ROLE: When Role dim < 7, always add a task-class-appropriate role to the strengthened prompt.

    line 206
  5. Distinctive:

    If no row matches, synthesize a role using this skeleton:

    line 246
  6. Distinctive:

    Always one role, not a list of options.

    line 265
  7. Distinctive:

    Always task-class appropriate — generic "AI assistant" framing is never the answer when Role < 7.

    line 272
  8. Distinctive:

    If the user's prompt already names a domain or seniority (e.g., "as a senior dev…"), preserve their wording and only add what's missing …

    line 276
  9. Distinctive:

    If the user's prompt explicitly contradicts a default role (e.g., "be casual" against a formal-default class), the user wins.

    line 279
  10. Distinctive:

    Never ship a default qualifier that contradicts the persona — a wrong audience frame is worse than no role at all (observed failure: a …

    line 283
  11. Distinctive:

    Use XML tags when prompts mix instructions, context, data, and constraints (3+ distinct parts).

    line 289
  12. Distinctive:

    Use 3-7 tags max — over-tagging adds noise.

    line 291
  13. Very specific:

    After category diagnosis, scan for words and phrases that weaken instruction clarity.

    line 306
  14. Distinctive:

    Pruning rule: every removal improves precision.

    line 342
  15. Distinctive:

    If no weaknesses are found (prompt scores clean), skip to STEP 4.5 (transcript) and STEP 4.6 (final preview) — these run even for Grade A …

    line 346
  16. Distinctive:

    Every rewrite preserves: same action verb, same target, same output type, no new requirements added beyond what the user implied.

    line 381
  17. Distinctive:

    Check for contradictions between added constraints

    line 394
  18. Distinctive:

    Add complexity only when it directly eliminates a diagnosed weakness

    line 399
  19. Distinctive:

    Keep terminology the user chose unless it causes ambiguity

    line 400
  20. Distinctive:

    Remove qualifiers and hedging language flagged in Step 1

    line 401
  21. Distinctive:

    Self-check gate: if the re-grade does NOT raise the overall score, the rewrite failed — return to STEP 2 and re-map fixes (max 2 retries, …

    line 413
  22. Very specific:

    Dispatch the context-blind Agent() reviewer: when stakes are high — self-grade ≤ B- (any C / D / F), OR claimed lift > 1.5 points, OR the …

    line 425
  23. Very specific:

    EVERY turn (STEP 3.6); its Reviewer-after column IS its grade card.

    line 468
  24. Distinctive:

    ALWAYS print the "Independent reviewer" line stating who it is and what it did.

    line 470
  25. Distinctive:

    Grade D warning line (locked format): when the prompt graded D, render this line ABOVE the grade card — the "heavy warning" is this exact …

    line 504
  26. Very specific:

    Update the *Enhanced:* indicator to include strengthening: *Enhanced: prompt strengthened (N fixes, Grade X), git state, 2 rules*

    line 518
  27. Distinctive:

    If the user wants per-dimension scores, they're in Step 4.

    line 551
  28. Very specific:

    OVER_SCOPED rendering: when Step 3 split the prompt into sequential focused sub-prompts, the Final block contains the numbered sequence — …

    line 597
  29. Very specific:

    When the strengthened prompt clearly fits a workflow other than direct execution (e.g., a high-stakes decision benefits from …

    line 612
  30. Very specific:

    If the turn produced committable changes, dispatch git-manager-agent to stage → secret-scan → commit (conventional + the Co-Authored-By …

    line 686
  31. Distinctive:

    No after-card renders on a grill turn — there is no strengthened prompt to re-grade yet.

    line 721
  32. Distinctive:

    Question budget: no upper limit. Ask one question at a time and keep asking until you have full confidence in the user's intent.

    line 732
  33. Distinctive:

    Read the codebase before asking — do not ask what you can answer yourself

    line 739
  34. Distinctive:

    If you can't cite one, you don't have enough context to recommend yet — read more code first instead of asking.

    line 767
  35. Distinctive:

    Quote-as-evidence: every dimension score cites a specific phrase from the prompt that justifies it.

    line 790
  36. Distinctive:

    Use case input: ask the user to describe the prompt's use case before scoring.

    line 792
  37. Distinctive:

    When the global rule detects that a user's prompt implies creating, updating, or deleting Claude Code resources (skills, agents, rules, …

    line 809
  38. Distinctive:

    CRUD Exception: when creating/updating a resource targeting an external technology, search the web for current docs — training data may be …

    line 881
  39. Distinctive:

    When in doubt, default to NO CRUD — do not suggest resource changes unless the signals are clear.

    line 930
  40. Very specific:

    Run STEP 0 (Quick Grade) before any diagnosis, and skip diagnosis for Grade A — with ONE exception: the cap-exempt MISSING_ROLE fix applies …

    line 939
  41. Distinctive:

    Run the Clarification Gate after strengthening when ambiguity remains — ask one question at a time, no upper limit

    line 943
  42. Distinctive:

    Read relevant code before asking a clarification question — asking answerable questions wastes the user's time

    line 944

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Prompt Auto-Enhance — Strengthening, Step Transcript, Final Preview, Resource CRUD

This skill strengthens non-trivial prompts before execution and shows the full working — every step's output, the final strengthened prompt, and the before/after comparison — so the user can see exactly what was changed and why. The prompt-auto-enhance global rule controls when this activates; the prompt-enhance-reminder.sh hook gates triggering at the deterministic layer (prompts ≤15 chars and continuation phrases never reach this skill).

Arguments: $ARGUMENTS


Activation

Activates for non-trivial free-text prompts — anything the hook did not filter out. Skipped at the hook layer for:

  • Slash commands — any /command, user-made OR Anthropic-provided (/init, /end-session, …), is run exactly as-is, any size (enhance_slash_commands: false, the canonical plugin default)
  • Prompts ≤ 15 characters (after trimming whitespace)
  • Known continuation phrases ("yes", "ok", "continue", "now do …", "also …", etc.)

Adapted from community pattern by @heyrimsha (source: x.com/heyrimsha/status/2035995286150234480).

ENHANCE_MODE — the session opt-out flag (auto | ask | off)

A session flag controls whether the prompt-enhancement pipeline (this skill's STEP 0–4.6 strengthening + the L3 reviewer-card / diagnosis-substance enforcement in no-overask-guard.sh) runs. The governance tail — plan-before-coding, decide-don't-ask, grill-when-unsure, narrate-and-stop, git — is always active in every mode; it is NOT part of the enhancement process and is never gated by this flag.

Storage: .claude/.enhance-mode (gitignored runtime file). Absent ⇒ auto — so default behavior is unchanged.

Set it inline — type one of these as a whole prompt; prompt-enhance-reminder.sh writes the flag and confirms: enhance auto · enhance ask · enhance off.

ModeBanner + grade card + reviewer + final-promptStop-hook enhance enforcementGovernance tail
auto (default)rendered every substantive turnon (reviewer-card + diagnosis blocks)on
asksuppressed; append one line "Enhance available — reply enhance…"offon
offsuppressed entirelyoffon

One-shot opt-in: in ask/off, a bare enhance (or enhance this) re-runs the PRIOR prompt through the full pipeline for that turn without changing the stored mode. Everything in the auto-mode contract below applies only when the mode is auto (or for that one-shot turn) — in ask/off the banner + full-process requirement is suspended (and the L3 hook will not block its absence), while the governance rules still hold.

STEP 0-pre: Transcription Normalization (runs BEFORE grading)

User prompts are often voice-dictated; transcription artifacts recur (observed examples: "brown tortoise enhancement" → prompt-auto-enhance, "this grant" → this prompt). Normalize BEFORE grading so STEP 0 scores the intended prompt, not the transcription noise.

Detect: filler tokens ("uh", "um"), stutters/repeats ("the the the", "how are how are"), mid-sentence restarts ("you had... you need to..."), and phonetic mishears — a noun phrase that is nonsense in context but phonetically resembles a repo/conversation term.

Act:

  1. Strip fillers/stutters/restarts silently (they carry no meaning).
  2. For each phonetic mishear, render a visible mapping line so the interpretation is auditable: heard: "<verbatim>" → read as: "<term>" (<phonetic|context> match)
  3. Load-bearing test: if the misheard word changes WHAT gets built (two plausible readings diverge materially), do NOT guess — route it to the Clarification Gate with a *Sync-check:* banner. If one reading is the only sensible one in context, proceed on it with the mapping shown.
  4. STEP 0 grades the NORMALIZED text; STEP 4.6 still shows the user's ORIGINAL verbatim (the mapping lines bridge the two).
  5. Render placement (locked): full mode → the mapping lines sit BETWEEN the Original and Final blocks in STEP 4.6; compact/format-A mode → they are the first line(s) of "What changed:". Never omitted when a mishear was resolved — an invisible reinterpretation is a guess.

STEP 0: Quick Grade

Score the prompt across 6 base dimensions (plus Tone if active) on a 1-10 scale. Only dimensions scoring below 7 are diagnosed.

DimensionDefault WeightWeight w/ Tone ActiveMeasures
Intent Clarity0.250.25Action verb + target + success criteria explicit
Context Sufficiency0.200.20All needed background present
Constraint Precision0.200.20Boundaries measurable and unambiguous
Output Specification0.150.15Expected result format defined
Role & Framing0.100.05Persona, domain, expertise level
Example Grounding0.100.05Input/output examples for complex tasks
Tone Consistency0.000.10Voice/register/audience (prose only)

Tone activation signals: prompt targets prose, creative writing, marketing copy, UX/UI text, email, blog post, tweet, landing page, error message text. Triggered by words like "write", "draft", "compose", "rewrite", "tone", "voice", "audience", "copy".

Score formula: Overall = Sum(weight_i x score_i) — Range 1.0-10.0

Grade thresholds:

GradeRangeAction
A≥ 8.0Skip strengthening — prompt is strong. Sole exception: the cap-exempt role fix still applies when Role dim < 7 (a role line never changes intent — Guardrail 2-safe; keeps the rule's MANDATORY-OUTPUT role contract grade-independent)
B[6.0, 8.0)Targeted fix — compact mode (1-2 fixes + the cap-exempt role fix when Role dim < 7)
C[4.0, 6.0)Full pipeline — diagnose all weak dimensions
D[3.0, 4.0)Full pipeline with heavy warning to user
F< 3.0Suggested rewrite with caveats — original may be unsalvageable

Bands are half-open intervals (fixed): the old "6.0-7.9"-style ranges left holes (a weighted score of 2.95 or 7.95 mapped to NO grade). Every score in [1.0, 10.0] now maps to exactly one grade.

Floor rules (precedence — first match wins):

  1. Intent Clarity OR Context Sufficiency scoring 1-2 → Grade F
  2. More than 5 Critical issues diagnosed → Grade F
  3. Any other single dimension scoring 1-2 → cap at Grade B (max 7.9)
  4. Otherwise → use the threshold table above

Dimension-to-Category mapping:

Dimension < 7Diagnose These Categories
Intent ClarityVAGUE_INTENT, AMBIGUOUS_SCOPE
Context SufficiencyMISSING_CONTEXT, IMPLICIT_ASSUMPTIONS
Constraint PrecisionUNDER_CONSTRAINED, CONFLICTING_CONSTRAINTS
Output SpecificationMISSING_OUTPUT_SPEC, MISSING_STRUCTURE
Role & FramingMISSING_ROLE
Example GroundingMISSING_EXAMPLES
Tone ConsistencyMISSING_TONE_FRAME (when Tone active)

Read: references/grading-rubric.md for full scoring anchors per dimension.

Diagnose only categories mapped from dimensions scoring < 7 — skip categories whose parent dimension already scores 7+.

Evidence-override lane: a CONCRETE flaw inside a dimension scoring ≥ 7 MAY still be fixed, under strict conditions: (a) the diagnosis quotes the exact offending fragment; (b) the fix counts against the 5-cap; (c) it is labeled [evidence-override] in Changes Applied. This closes the gap where a strong prompt carries one real defect (a wrong domain fact, a contradictory clause) that the dimension gate would otherwise make unfixable — found when an ambiguous term in an Intent-7 prompt had no legal fix. No quote → no override; "could be better" never qualifies.

STEP 1: Diagnose Prompt Weaknesses

Analyze the prompt against the failure category table. Classify every weakness found — a prompt may have multiple.

Failure Category Table

CategorySeveritySymptomsStructural Fix
VAGUE_INTENTCriticalUnclear what the user wants done; could be interpreted multiple waysRewrite as specific action verb + object + success criteria
MISSING_CONTEXTCriticalPrompt assumes knowledge not provided (file paths, prior decisions, domain terms)Add explicit context: which files, which module, what prior state
CONFLICTING_CONSTRAINTSHighPrompt asks for contradictory things ("make it fast and thorough")Identify the conflict, prioritize one, note the tradeoff
OVER_SCOPEDHighAsks for too many things at once; would require 5+ files changedBreak into sequential focused prompts, suggest ordering
UNDER_CONSTRAINEDMediumVague where specificity is needed. Apply the measurability test: "Can a reviewer objectively verify this constraint was followed?" (see references/constraint-engineering.md)Add measurable constraints. Replace vague terms ("be concise" -> "under 100 words", "be thorough" -> "cover all N checklist items"). When the measurable value is user-owned (a target, tolerance, or acceptance number only the user can set — e.g. "more accurate" → accurate against WHAT, to WHAT tolerance), defer it to the Clarification Gate exactly like MISSING_CONTEXT — never invent the number (Guardrail 2) and never leave the vague term standing
MISSING_OUTPUT_SPECMediumNo indication of what the result should look likeAdd a locked output template with named sections, explicit order, numeric length bounds (see references/format-locking.md)
AMBIGUOUS_SCOPEMediumUnclear which files, modules, or layers are in scopeAdd explicit scope boundaries ("only in src/api/", "just the tests")
IMPLICIT_ASSUMPTIONSLowPrompt relies on assumptions that may not hold (env setup, dependencies, prior steps)Make assumptions explicit or add verification steps
MISSING_STRUCTURELowMulti-part prompt uses flat unstructured text where XML tags would improve clarityRestructure with XML tags (see XML Tag Reference below)
MISSING_ROLEMediumNo explicit persona or domain frame (Role dim < 7)Always add a task-class-appropriate role using the "Role Selection Guide" below — never skip
MISSING_EXAMPLESLowNo input/output examples for complex tasksAdd 2-3 diverse examples in <examples> tags
MISSING_TONE_FRAMEMedium (Tone-active prompts only)No voice, register, or audience guidance for prose outputAdd tone spec: register (formal/casual), audience, length bounds, voice attributes

Severity handling:

SeverityBehavior
CriticalAlways included — Critical fixes are never capped
HighIncluded up to the max changes cap
MediumIncluded up to the max changes cap
LowIncluded only if budget remains

Role Selection Guide

Policy: never skip MISSING_ROLE. When Role dim < 7, always add a task-class-appropriate role to the strengthened prompt. Position the role as the first line, before context. Use the imperative form (Act as a …) — Anthropic's prompting docs document this as the strongest persona pattern for Claude 4.x.

R1 ≠ R2 — the conflation that caused real misses: the Role: <name> — <why> line rendered at STEP 4.7 is the R2 operating engineering role (engineering-roles.md) and does NOT satisfy this policy. R1 is the persona INSIDE the strengthened prompt text — the Final-prompt block (STEP 4.6) MUST open with Act as … whenever Role & Framing < 7, even when an R2 Role: line is also rendered in the same response. Rendering the R2 line while leaving the prompt text roleless is the exact defect this paragraph exists to prevent.

Detect the task class from the prompt's main verb + nearest object, then pick the role from the table. If no row matches, fall back to the template at the bottom.

Task classDetection signalsDefault role
Mechanical executionrename, move, run, delete, format, list (no specialty)"Act as a careful engineer who executes mechanical changes without scope creep — no refactors, no comments, no surrounding cleanup."
Standard implementationimplement, add, fix, update (clear scope, no specialty)"Act as a senior software engineer who writes simple, idiomatic code in the surrounding style and avoids speculative abstraction."
Information retrievalwhat is, explain, describe, where is, how does"Act as a senior engineer who explains code precisely, citing specific files and line numbers as evidence."
Specialized analysis — securityreview, audit, evaluate + (auth / token / session / SQL injection / XSS / OWASP / threat)"Act as a security auditor focused on OWASP Top 10 — flag injection, broken auth, broken access control, and sensitive data exposure with specific code references."
Specialized analysis — perfreview, audit, profile + (latency / p95 / p99 / slow / bottleneck / N+1 / cache)"Act as a performance engineer specializing in p95/p99 latency analysis — identify N+1 queries, cache misses, allocation hot paths, and serialization overhead with measurements."
Specialized analysis — accessibilityreview, audit + (a11y / accessibility / WCAG / aria / contrast / screen reader / keyboard)"Act as an accessibility auditor working from WCAG 2.2 AA — flag color contrast failures, keyboard nav gaps, ARIA misuse, and screen-reader hazards with line-level fixes."
Specialized synthesis — system designdesign, architect + (system / service / pipeline / scale / distributed)"Act as a staff engineer designing for the stated scale and failure modes. Call out trade-offs, rejected alternatives, and the failure cases your design does NOT handle."
Specialized synthesis — API designdesign, define + (API / endpoint / schema / contract / interface)"Act as an API designer optimizing for backwards compatibility, naming consistency, and a clean error surface. Surface every breaking change risk explicitly."
Specialized synthesis — data modelingdesign, model + (schema / table / DB / migration / index)"Act as a database engineer who optimizes schemas for the stated query pattern, write throughput, and migration safety. Call out N+1 and lock contention risks up front."
Tone-sensitive — onboarding/UXwrite, draft + (onboarding / welcome / first-time / activation)"Act as an onboarding copywriter who writes for first-time non-technical users — warm + professional, second-person, no jargon, scannable structure."
Tone-sensitive — error/UX stringswrite, draft + (error / warning / banner / toast / empty state)"Act as a UX writer specializing in error messages — clear about what went wrong, actionable about what to do next, never blames the user, max 1 sentence."
Tone-sensitive — marketing copywrite, draft + (landing / hero / pitch / launch / announcement)"Act as a marketing copywriter focused on benefit-led messaging that respects the reader's intelligence — no hype, no buzzwords."
Tone-sensitive — developer docswrite, draft + (docs / README / guide / how-to / tutorial)"Act as a technical writer specializing in developer documentation — accuracy first, scannable structure, copy-pasteable examples, every claim verified against current code."
Advisory / decision supportshould we, recommend, compare, trade-off, evaluate options"Act as a senior engineer who gives opinionated, source-cited recommendations grounded in stated constraints. Name a default position with reasoning, not a multiple-choice menu."
Translation / adaptationrewrite for X audience, port from Y to Z, simplify, expand"Act as a translator who preserves the source's intent and structure while replacing tone/idiom for the target audience. Flag every place where literal translation breaks meaning."
Bug investigationdebug, why is, what's wrong, find root cause"Act as a root-cause debugger who reproduces before hypothesizing — isolate the failure, gather evidence, name the smallest hypothesis that explains all observed symptoms."

Template for novel task classes:

If no row matches, synthesize a role using this skeleton:

Act as a <senior|specialized> <profession> who <does the task verb> with
attention to <1-2 specific failure modes>.

Worked example: prompt is "design the feature flag schema for a global rollout" — no exact row match, but it's a synthesis task with data modeling + reliability concerns. Synthesized role:

Act as a feature-flag platform engineer who designs schemas for global
rollouts with attention to staleness, cache invalidation, and the
delete-flag lifecycle.

Rules for role selection:

  • Always one role, not a list of options.
  • Tie-break when 2+ rows match: pick the row matching the prompt's PRIMARY deliverable — the outcome the user would accept as "done" — not the means mentioned along the way ("add indexes to make queries faster" → faster queries is the deliverable, indexes the means → perf row, not data modeling). If two deliverables are genuinely co-primary, that is an OVER_SCOPED signal: split, and give each sub-prompt its own role.
  • Always task-class appropriate — generic "AI assistant" framing is never the answer when Role < 7.
  • Position the role as the first line of the strengthened prompt, before context.
  • If the user's prompt already names a domain or seniority (e.g., "as a senior dev…"), preserve their wording and only add what's missing (concerns, focus area).
  • If the user's prompt explicitly contradicts a default role (e.g., "be casual" against a formal-default class), the user wins.
  • Adapt the audience qualifier to the documented product persona (CLAUDE.md / the product plan): B2B vs B2C, technical vs non-technical. Never ship a default qualifier that contradicts the persona — a wrong audience frame is worse than no role at all (observed failure: a table's old "B2B" defaults contradicted a product's documented B2C persona).

XML Tag Reference

Use XML tags when prompts mix instructions, context, data, and constraints (3+ distinct parts). Skip for simple single-intent queries or 1-2 sentence prompts. Use 3-7 tags max — over-tagging adds noise.

Core tags: <task> (what to do), <context> (background), <instructions> (steps), <constraints>/<rules> (limits), <output_format> (result shape), <examples> (few-shot), <input> (variable data), <documents> (multi-doc context), <thinking> (reasoning), <answer> (final output).

Rules: descriptive tag names (<patient_records> not <data1>), nest for hierarchy, place long context ABOVE the query, do not wrap single sentences.

Reference: See references/constraint-engineering.md for the full constraint engineering methodology and measurability test table.

Weakening Language Flags

After category diagnosis, scan for words and phrases that weaken instruction clarity. These are automatic flags — every occurrence is evaluated for removal or replacement (see references/prompt-pruning.md for the full source pattern):

Category A — Hedging & Filler:

Flag PatternProblemReplace With
"try to", "attempt to"Permits failure as acceptableDirect imperative ("do X")
"if possible", "when feasible"Creates an opt-out clauseRemove, or state the specific condition
"maybe", "perhaps", "might"Introduces uncertainty into instructionsCommit to a direction or use conditional logic
"I think", "I believe"Weakens authority of the instructionState the requirement directly
"please", "kindly"Politeness filler in technical promptsRemove — instructions are not requests
"etc.", "and so on", "and more"Unbounded scopeList all items explicitly
"simple", "just", "easily"Minimizes complexity, sets false expectationsRemove — let the task speak for itself
"as needed", "as appropriate"Delegates decision without criteriaSpecify the criteria for when/how
"feel free to"Implied optionality for required behaviorRemove
"don't worry about"Unclear exclusion scopeState what TO do
"roughly/approximately" (when precision needed)Vague threshold where exact value mattersState exact threshold

Category B — Aggressive Enforcement Anti-Patterns (Claude 4.x specific)

Flag PatternProblemReplace With
"CRITICAL:/IMPORTANT:/YOU MUST"Aggressive emphasis degrades compliance in newer modelsNormal directive
"NEVER EVER/ABSOLUTELY MUST"Over-emphatic phrasing triggers resistanceStandard MUST/NEVER
"think step by step" (reasoning models)Redundant for models with built-in reasoning"evaluate"/"reason through"

Category C — Output-Side Anti-Patterns (model self-correction)

Flag PatternProblemReplace With
"Certainly!/Of course!/Absolutely!"Sycophantic opener wastes tokensLead with the answer
"Based on the information provided..."Filler preambleRemove
"I'd be happy to help with..."Unnecessary pleasantryRemove

Pruning rule: every removal improves precision. Cutting words just to reduce length is not pruning. If a qualifier serves a real purpose ("if the file exists" is a real condition, not hedging), keep it.

If no weaknesses are found (prompt scores clean), skip to STEP 4.5 (transcript) and STEP 4.6 (final preview) — these run even for Grade A to maintain uniform transparency.

STEP 2: Map Fixes

For each diagnosed weakness, determine the minimal structural fix. Each fix maps to exactly one failure category — no fix without a diagnosis, no diagnosis without a fix.

Format:

Diagnosis:
  [1] CATEGORY_NAME → specific fix description
  [2] CATEGORY_NAME → specific fix description

STEP 3: Rewrite with Guardrails

Apply all fixes to produce a strengthened version.

Guardrail 1: Max Changes Cap

  • Maximum 5 non-Critical fixes per rewrite
  • Critical severity fixes are never capped — apply all of them
  • The MISSING_ROLE fix is likewise cap-exempt (treated like Critical): whenever Role & Framing < 7, the Act as … line is added — including in Grade-B compact mode, whose 1-2-fix budget applies to the OTHER fixes. Rationale: roleless-but- otherwise-decent prompts land exactly in compact mode, which previously starved the role fix out (observed in production sessions).
  • Grade D: full pipeline runs but show a heavy warning
  • Grade F: present a suggested rewrite with caveats (original may need rethinking)

Guardrail 2: Intent Preservation Check (hard contract)

Every rewrite preserves: same action verb, same target, same output type, no new requirements added beyond what the user implied. Verify before presenting.

OriginalRewrittenVerdict
PASS"fix the login bug — error in screenshot attached""fix the login bug shown in the screenshot — restore expected behavior"Same intent, sharpened wording
FAIL"review auth module""refactor auth module to use JWT"Changed intent from review to refactor
FAIL"fix the login bug""resolve auth failure in login.py:42"Invented file/line that user did not specify — move file-pinning into Clarification Gate, not the rewrite

Guardrail 3: Over-Constraint Detection

  • Soft warning if >3 constraints added in a single rewrite
  • Hard gate: intent preservation (Guardrail 2) overrides constraint additions
  • Check for contradictions between added constraints

General rewrite rules:

  • Targeted changes only — leave clear parts alone
  • Preserve the user's original intent and voice
  • Add complexity only when it directly eliminates a diagnosed weakness
  • Keep terminology the user chose unless it causes ambiguity
  • Remove qualifiers and hedging language flagged in Step 1
  • For MISSING_STRUCTURE diagnoses, wrap distinct sections in XML tags
  • Long context above the query, constraints near the task definition

STEP 3.6: Re-Grade the Strengthened Prompt

Re-score the strengthened prompt on the SAME rubric and weights as STEP 0. This is the proof-of-lift: the pipeline's contract is "rank the prompt, enhance to a higher number, then run it" — not "rewrite and hope".

  • Render the lift as Overall: <before> → <after> (Grade <X> → <Y>) — it appears in the Step 4 grade card and the Step 4.5 transcript.
  • Self-check gate: if the re-grade does NOT raise the overall score, the rewrite failed — return to STEP 2 and re-map fixes (max 2 retries, then surface the failure honestly instead of presenting a non-improving rewrite).
  • Grade-A originals (role-only addition) typically move a few tenths via the Role dimension — that small lift is expected and sufficient.

Independent re-grade — the Reviewer-after card column is MANDATORY every enhanced turn; the BLIND Agent() dispatch is STAKES-THRESHOLDED (audit gap G8, 2026-06-18): the self re-grade is scored by the same model that wrote the rewrite — structurally motivated to show lift (the author-verifies-own-work blind spot — see independent-test-verification.md). So the Reviewer-after column is rendered on EVERY non-trivial enhanced turn, but HOW it is produced scales with stakes so the cost never makes the whole card get silently dropped:

  • Dispatch the context-blind Agent() reviewer when stakes are high — self-grade ≤ B- (any C / D / F), OR claimed lift > 1.5 points, OR the turn does destructive / irreversible / wide-scope / domain-critical work. Label the column (blind agent); its number WINS the lift.
  • Otherwise (Grade-A/B, small-lift, low-stakes turns) do a CHEAP self spot-check — adversarially re-grade only the 2 LOWEST dimensions + sanity-check the overall — and label the column (self spot-check). The column is unconditional (the enforcement hook always sees it); only the expensive blind dispatch is proportional to stakes — an unaffordable per-turn mandate is what gets dropped.

Who the reviewer is (state this in the output every time): a context-blind subagent — a fresh model instance dispatched via Agent() that receives ONLY the original prompt, the strengthened prompt, and the rubric (the 6 dimensions + weights inline, or the references/grading-rubric.md path) — never the pipeline's own scores, narrative, or reasoning. It cannot see how the rewrite "wants" to score, which is what makes it independent.

Mechanism (keep it lean — it runs per turn): dispatch the reviewer with the rubric INLINED (6 dimensions + weights + grade bands) and ask for ONLY the two score tables + the two overalls + a one-line verdict — no rationale paragraphs, no file reads unless a value is disputed. The reviewer scores both prompts and returns both overalls. ALWAYS report, in the STEP 4 after-card: (1) WHO the reviewer is + WHAT it did, and (2) its independent score — and the blind number WINS the rendered lift (the self-score never overrides it). If |blind_after − self_after| > 1.0, also log regrade-divergence to .claude/.enhance-misses.log (the over-scoring telemetry).

STEP 4: Show Grade Card + Changes Applied

Step 4 is metadata only — grade card with per-dimension scores and a one-line list of every fix the rewrite intends to apply. The full prompt text (original → strengthened) is rendered exactly once, in STEP 4.6, after the Clarification Gate has resolved any pending values. This avoids "pending" placeholders inside Step 4 and gives the prompt text a single source of truth.

Compact mode (Grade A or B with 1-2 fixes):

Grade: B (7.4 / 10) — 1 fix applied
  [1] UNDER_CONSTRAINED → added output format spec

Full mode (default — Grade C/D/F and any turn with strengthening): render a card with FOUR score columns per dimension — Before, Self-after, Reviewer-after, Weight — so the independent reviewer's full per-dimension grade card is VISIBLE, not just its two overalls. The independent reviewer runs EVERY turn (STEP 3.6); its Reviewer-after column IS its grade card. The BLIND overall is the rendered Overall-after (self-after shown only for comparison), and ALWAYS print the "Independent reviewer" line stating who it is and what it did. The Reviewer-after column is NOT optional — omitting it (showing only the reviewer's overall) is the exact gap this format closes.

Prompt Grade Card (before → after — self vs independent reviewer):
┌────────────────────────┬────────┬────────────┬────────────────┬────────┬───────┐
│ Dimension              │ Before │ Self-after │ Reviewer-after │ Weight │ Fix   │
├────────────────────────┼────────┼────────────┼────────────────┼────────┼───────┤
│ Intent Clarity         │  4.0   │   9.0      │   9.0          │  0.25  │ [1]   │
│ Context Sufficiency    │  2.0   │   7.0      │   6.0 ⚠framed  │  0.20  │ [2]   │
│ Constraint Precision   │  1.0   │   9.0      │   9.0          │  0.20  │ [3]   │
│ Output Specification   │  1.0   │   8.0      │   8.0          │  0.15  │ [4]   │
│ Role & Framing         │  1.0   │   9.0      │   9.0          │  0.10  │ [5]   │
│ Example Grounding      │  2.0   │   7.0      │   6.0          │  0.10  │ —     │
├────────────────────────┼────────┼────────────┼────────────────┼────────┼───────┤
│ Overall                │  2.05  │   8.20     │  7.85 (wins)   │        │ F → B │
└────────────────────────┴────────┴────────────┴────────────────┴────────┴───────┘
Independent reviewer (ran this turn — no exceptions): a context-blind Agent() subagent
  re-graded both prompts from the rubric alone; it never saw the self-scores. The
  Reviewer-after column above IS its grade card. Reviewer overall 7.85 (B) WINS over
  self 8.20 (A); divergence 0.35 < 1.0 → no flag, but the blind number still wins.

Changes Applied (5):
  [1] VAGUE_INTENT (Critical) → action verb chain (measure → cache → prove)
  [2] MISSING_CONTEXT (Critical) → defer to Clarification Gate Q1
  [3] UNDER_CONSTRAINED (Medium)  → replace vague phrase with measurable target
  [4] MISSING_OUTPUT_SPEC (Medium)→ add deliverable triple
  [5] MISSING_ROLE (cap-exempt)   → prepend task-class persona
  Pruning: removed "so it's faster" (Cat A — vague threshold)

Each After score that rose MUST be earned by a listed Fix [n] — a lift with no fix behind it is an inflated number; flag it ⚠framed (improved framing, unresolved substance) rather than crediting full points.

Grade D warning line (locked format): when the prompt graded D, render this line ABOVE the grade card — the "heavy warning" is this exact string, not an improvised paraphrase:

⚠ Grade D (<score>/10): this prompt needed heavy reconstruction — review the
Final Prompt block before relying on the execution.

Step 4 deliberately does NOT show the original or strengthened prompt text — that's STEP 4.6's job. Showing it here would either duplicate Step 4.6 (when no clarification is pending) or require a "[pending]" placeholder cell (when one is). Both were judged worse than splitting metadata from text.

Update the *Enhanced:* indicator to include strengthening: *Enhanced: prompt strengthened (N fixes, Grade X), git state, 2 rules*

STEP 4.5: Show Step Transcript

Render a compact transcript of pipeline counts and deltas only — no per-dimension scores, no per-category enumeration, no per-fix list. Those already live in Step 4's grade card and Changes Applied. The transcript is the audit trail (what ran, how many, how long), not a recap of the diagnosis.

Transcript format:

Pipeline Transcript:
  Step 0 — Quick Grade:    <Grade letter> (<overall score> / 10), Tone dim: <yes|no>
  Step 1 — Diagnose:       <N> categories flagged (Critical: <X>, High: <Y>, Medium: <Z>, Low: <W>)
  Step 1b — Pruning Flags: <N> weakening phrases found
  Step 2 — Map Fixes:      <N> fixes mapped (<X> Critical applied uncapped, <Y> non-Critical within 5-cap)
  Step 3 — Rewrite:        <N> changes applied; word count <before> → <after> (Δ <delta>)
                           Guardrail 2 (Intent Preservation): PASS|FAIL[, reason]
                           Guardrail 3 (Over-Constraint): clean | <N> constraints added
  Step 3.6 — Re-Grade:     Overall <before> → <after> (Grade <X> → <Y>) — lift confirmed|FAILED
  Clarification Gate:      <N> questions asked, <resolved|in-progress>

For Grade A:

Pipeline Transcript:
  Step 0 — Quick Grade:    A (8.6 / 10) — strengthening skipped
  Steps 1-4:               n/a (Grade A)

This block is informational only — the user does not need to act on it. If the user wants per-dimension scores, they're in Step 4. If they want the per-fix list, that's also in Step 4. If they want the actual prompt text, that's in Step 4.6. Transcript stays metadata.

STEP 4.6: Show Original → Final Strengthened Prompt

The single source of truth for the actual prompt text. Render the original prompt and the final strengthened prompt in fenced blocks so the user can diff them visually. Step 4 owns the metadata (scores, change list); Step 4.6 owns the text. No other step renders the prompt — duplication is intentionally avoided.

Format (with strengthening applied):

─── Original Prompt ───

<the original prompt verbatim>

─── Final Strengthened Prompt (will execute next) ───

<the strengthened prompt verbatim — all Clarification Gate values filled in>

────────────────────────────────────────────────────

For Grade A with Role dim ≥ 7 (no changes — original IS the final prompt):

─── Final Prompt (unchanged from original) ───

<original prompt verbatim>

────────────────────────────────────────────

For Grade A with Role dim < 7 (the sole Grade-A change — role line prepended, body untouched):

─── Final Prompt (role added; otherwise unchanged) ───

Act as …

<original prompt verbatim>

────────────────────────────────────────────

OVER_SCOPED rendering: when Step 3 split the prompt into sequential focused sub-prompts, the Final block contains the numbered sequence — each sub-prompt opens with its OWN task-class R1 role (a split under one generic role re-creates the role-miss inside every sub-task) — followed by a one-line ordering rationale. STEP 5 executes the sub-prompts in the stated order in the same turn (build-don't-narrate), unless the user picks a subset.

The skill does not pause for approval here — execution proceeds to STEP 5 in the same response. Showing the final prompt is for transparency, not gating. The Clarification Gate has already resolved before this step, so the strengthened block contains real values, not placeholders.

Optional skill hint (advisory, not selection)

When the strengthened prompt clearly fits a workflow other than direct execution (e.g., a high-stakes decision benefits from /five-advisors, unclear requirements benefit from /brainstorm, a multi-step build benefits from /writing-plans), append ONE italic line after the final prompt block:

*Related skills for this kind of prompt: <skill-1> (<one-clause why, with
quoted fragment from the user's prompt>), <skill-2> (<one-clause why>).
Invoke manually in a follow-up turn if useful — proceeding with the
strengthened prompt now.*

Rules:

  • One line. Italic. Maximum 2 skills.
  • Cite the strongest single matched fragment from the user's prompt for each suggestion (same one-quote rule as the Clarification Gate's "Why" line).
  • Informational only — never gating, never numbered, never selectable. STEP 5 still executes the strengthened prompt regardless.
  • The auto-enhance skill's primary job is prompt enhancement, not execution routing. The hint is a hint, not a recommendation engine.

When to skip the hint entirely (no advisory text appended — this is the default; only append when there is clear, unambiguous signal):

  • Direct implementation, mechanical execution, bug-fix, factual lookup, documentation request, or any prompt where the user clearly wants direct action
  • Prompt already names a skill explicitly ("run /tdd on this", "use /fix-loop")
  • Grade F prompt (original needs rethinking before any execution mode is even relevant)
  • Resource CRUD batch approval already active in this turn

Example (decision-shape match):

─── Final Strengthened Prompt (will execute next) ───

[strengthened prompt body]

────────────────────────────────────────────────────

*Related skills for this kind of prompt: /five-advisors (high-stakes
decision — "$97 workshop or $497 course"), /brainstorm (multi-option
tradeoff exploration). Invoke manually in a follow-up turn if useful —
proceeding now.*

Example (implementation-shape — no hint appended): the strengthened prompt block ends and STEP 5 runs. The user is not interrupted with a suggestion to use /tdd or /development-loop — those are direct-action intents the user already framed clearly.

STEP 4.7: Route to a role

Infer the engineering/PM role from the strengthened prompt and state it in one line: Role: <name> — <why>. Dispatch that role's backing agents/skills; sequence roles for multi-part work. Full router + role list: engineering-roles.md (pointer pattern — do not duplicate the table here).

STEP 5: Execute (under decision-authority)

Proceed with the strengthened prompt as if the user had entered it directly. The rest of the auto-enhance pipeline (Tier 1/2 context, CRUD detection) applies to the strengthened version, not the original.

Classify each decision under DACI (decision-authority.md):

  • DECIDE reversible / internal / best-practice-clear work — just do it, report after
  • DECIDE + INFORM tactical product calls — do it, drop a one-line note
  • ESCALATE irreversible / outward-facing / financially-material / strategic / genuine-fork — one line with a recommended option, and keep working every non-gated item

STEP 6: Git (conditional)

If the turn produced committable changes, dispatch git-manager-agent to stage → secret-scan → commit (conventional + the Co-Authored-By trailer) → push; .githooks/pre-commit is the deterministic secret gate. Branch + --no-ff merge for cohesive multi-file work; gate scaled to the change (code → type-check + tests, docs → cross-ref check). Skip git entirely on Q&A / read-only turns. Escalate only destructive history ops (force-push, rewrite of pushed commits, hard reset or deletion of main). Detail: decision-authority.md → "Git authority".

When NOT to Strengthen

When NOT to Strengthen

Most filtering happens at the hook layer. Within the skill, additional skips:

ConditionAction
Grade A (8.0+)Skip strengthening (except the cap-exempt role fix when Role dim < 7); still show transcript + final prompt
User says "do exactly this" or quotes a specific commandSkip strengthening; still show transcript + final prompt
Pure knowledge question (not an action request)Skip strengthening; just answer
Action-oriented question ("how should I test this?")Strengthen before answering

Clarification & Confidence Gate

The gate runs AFTER strengthening and BEFORE STEP 4.6 (final prompt preview), so the previewed prompt reflects the resolved intent. It is tiered (merges the lightweight clarification gate with the decision-authority.md confidence gate):

  • Exactly 1 small gap (a single unanswerable detail) → the Clarification Gate below (one targeted question at a time, locked format).
  • ≥2 distinct material unknowns, OR a fork that is expensive to reverse / materially changes the product / has no clear best-practice winner (confidence in WHAT to build < ~95%) → route to /grill-me (or /grill-with-docs when the decision should be recorded into CONTEXT/ADRs) and converge BEFORE strengthening — do NOT collapse multiple forks into a single clarification question, and do NOT guess. Concrete routing test: if the strengthened prompt would defer 2+ separate Q1-style placeholders, that is a grill, not one Clarification question. No after-card renders on a grill turn — there is no strengthened prompt to re-grade yet.
  • "You take a call" / pre-authorized → gate waived; proceed on best judgment, stating one-line assumptions.

Confidence is about intent, never a reversible execution detail (those are just decided in STEP 5).

Trigger: the prompt is > 15 characters (the only floor — handled deterministically by the hook). For every prompt that reaches this skill, evaluate whether ambiguity remains after strengthening. If yes, ask clarifying questions.

Question budget: no upper limit. Ask one question at a time and keep asking until you have full confidence in the user's intent. Stop when confidence is reached, not when a question count is hit.

How:

  • One question per turn, with a count ("Question N of unbounded") and a recommendation labeled clearly
  • Read the codebase before asking — do not ask what you can answer yourself
  • Each question must be unanswerable from Tier 1/2 context
  • Present any plan section by section after questions resolve, not all at once

Question format (locked template):

*Sync-check:* Question N of unbounded — Clarification Gate

<one specific question, unanswerable from Tier 1/2 context>

Recommendation: <a single concrete value — file path, command, scope, etc. —
                 not a list of options, not a hedge>.
Why: <one sentence citing a specific source — file path with line number,
      commit SHA, pattern name, or CLAUDE.md section — that informs the
      guess. No hand-wave reasoning>.

(Confirm, correct, or specify a different value.)

The gate opens with the *Sync-check:* marker because it IS a genuine required-intent question, not a permission-to-start over-ask — the no-overask-guard.sh Stop hook EXEMPTS that marker (decision-authority.md "Confidence gate"). Without it, a fired gate (and any rendered demo of one) trips the over-ask guard.

Rules for this format:

  • The Recommendation is a single value, not a multiple-choice list. The user can override it, but the default position is opinionated.
  • The Why line cites a specific source (file:line, SHA, pattern name). If you can't cite one, you don't have enough context to recommend yet — read more code first instead of asking.
  • The question stem is one sentence, ending with a question mark. Multi-part questions become multiple turns.

Sequencing summary:

  1. STEP 0-3: grade, diagnose, rewrite (internal)
  2. STEP 4: show grade card + Changes Applied (metadata only — no prompt text)
  3. Clarification & Confidence Gate (if ambiguity/consequential fork remains — ask one question, or /grill-me for a consequential fork under ~95% confidence)
  4. STEP 4.5: show step transcript (counts and deltas only — no per-dim or per-fix lists)
  5. STEP 4.6: show original → final strengthened prompt; OPTIONALLY append a one-line italic skill hint when the prompt clearly fits a non-direct-execution workflow (advisory only, never gating)
  6. STEP 4.7: state Role: <name> — <why> and dispatch its agents/skills (engineering-roles.md)
  7. STEP 5: execute the strengthened prompt under decision-authority (decide reversible; escalate irreversible in one line)
  8. STEP 6: if the turn produced committable changes, git via git-manager-agent + the secret-scan hook (skip on Q&A / read-only turns)

Verbose Grade Mode (replaces former Reliability Scoring)

Activates when the user explicitly asks to score, evaluate, or audit a prompt — not during automatic strengthening. Verbose mode runs the same 6-7 dimension Quick Grade rubric, with three additions:

  1. Quote-as-evidence: every dimension score cites a specific phrase from the prompt that justifies it. Score with no quote → invalid.
  2. Use case input: ask the user to describe the prompt's use case before scoring. The same prompt scores differently for a CLI tool vs. a customer chatbot.
  3. Launch-risk flagging: dimensions scoring below 7 are labeled "launch risks" with: the offending quote, the failure mode it will cause in production, and the concrete fix that would raise the score to 7+.

Verbose mode produces a report only — it does not auto-strengthen. If the user asks to fix afterwards, feed the launch risks into Steps 1-5 of the strengthening pipeline.

Read: references/grading-rubric.md for the verbose-mode subsection with the report template and verdict thresholds.


Batch Approval Flow

When the global rule detects that a user's prompt implies creating, updating, or deleting Claude Code resources (skills, agents, rules, hooks), execute this flow.

Step 1: Show Enhancement Summary

Enhancement Summary:
  Intent: [interpreted user intent in one sentence]
  Context gathered:
    - [Tier 1/2 sources read, e.g., "CLAUDE.md", "git status", ".claude/rules/"]
    - [Web sources fetched, if any]
  Reasoning: [why resource changes are needed]

Step 2: Present Batch Table

List ALL proposed resource changes in a single table:

Proposed resource changes:
  [1] CREATE rule:  <name>  — <one-line description>
  [2] UPDATE skill: <name>  — <what changes>
  [3] DELETE hook:  <name>  — <why obsolete>
  [4] CREATE agent: <name>  — <one-line description>

Approve which? (all / none / 1,3 / ...)

Rules for the batch table:

  • Group related changes together (e.g., a skill + its supporting rule)
  • For items where purpose or content cannot be determined with confidence, append [NEEDS CLARIFICATION: <question>] and let the user clarify
  • Show the action verb (CREATE / UPDATE / DELETE) and resource type for each

Step 3: Wait for User Selection

The user responds with one of:

  • all — approve every item
  • none — reject everything, proceed with the original prompt normally
  • 1,3 — approve only items 1 and 3 (comma-separated numbers)
  • Clarification text — answer to a [NEEDS CLARIFICATION] question; update the batch table and re-present

Step 4: Execute Approved Items

For each approved item, delegate to the appropriate authoring tool:

Resource TypeDelegate ToHow
Skill/writing-skillsSkill(skill="writing-skills") with the skill name and description
Rule/claude-guardianSkill(skill="claude-guardian") with the rule text
Agentskill-author agentAgent(prompt="Create agent: <description>", subagent_type="skill-author")
HookManual workflowCreate shell script in .claude/hooks/, update settings.json

Execute items sequentially — each resource may depend on the previous one (e.g., a skill might reference a rule created in the same batch).

Step 5: Skip Rejected Items

Items the user did not approve are dropped silently. Do not re-prompt for rejected items later in the same session.


Web Search Decision Tree

Skip web search when: prompt is about existing code, answer is in CLAUDE.md or .claude/ patterns, or it is general programming knowledge. Search the web only for: external library/API docs (when no local code exists), version / compatibility / deprecation questions, official framework conventions. Read local code first when local config exists for the library.

CRUD Exception: when creating/updating a resource targeting an external technology, search the web for current docs — training data may be outdated.


Context Gathering Reference

Tier 1 — Always (every prompt that reaches this skill)

SourceWhat to ReadWhy
.claude/ patternsGlob("core/.claude/{rules,skills,agents,hooks}/**") and Glob(".claude/{rules,skills,agents,hooks}/**")Know what exists to avoid duplication
CLAUDE.mdAlready loaded by systemArchitecture, commands, conventions
Git stategit status, git log --oneline -5Current branch, recent work, uncommitted changes

Tier 2 — Conditional

SourceWhen to ReadWhat to Read
Nearby filesPrompt mentions a specific file/feature/moduleImports, dependencies, tests, related modules
registry/patterns.jsonPrompt involves pattern creation or comparisonCheck if pattern already exists, verify sync

CRUD Detection Signals

CREATE signals

  • User describes a repeated workflow they do manually
  • User states a convention that should always be followed
  • User asks "can we enforce X" or "how do I make Claude always do Y"
  • User describes a review persona or specialized analysis task

UPDATE signals

  • User corrects Claude's behavior that an existing rule/skill should have caught
  • User says "also do X when running /skill-name"
  • User extends a convention beyond what the current rule covers
  • Existing pattern is outdated or incomplete for the user's needs

DELETE signals

  • User says "we no longer use X" or "remove the X rule"
  • User's codebase has migrated away from a technology a pattern targets
  • A pattern contradicts a newer pattern the user approved

NO CRUD signals

  • User asks a question (just answer it)
  • User asks to implement a feature (just implement it)
  • User asks to fix a bug (just fix it)
  • User asks to run tests (just run them)

When in doubt, default to NO CRUD — do not suggest resource changes unless the signals are clear.


Pipeline Rules

These are the load-bearing contracts. The rest of the skill is procedure.

  • Run STEP 0 (Quick Grade) before any diagnosis, and skip diagnosis for Grade A — with ONE exception: the cap-exempt MISSING_ROLE fix applies at every grade, A included, whenever Role dim < 7
  • Gather Tier 1 context before responding to any prompt — without it, responses risk duplicating existing patterns or contradicting CLAUDE.md
  • Show the grade card, step transcript, and final prompt every time strengthening activates — silent changes erode trust
  • Include the strengthening count in the *Enhanced:* indicator when fixes are applied
  • Run the Clarification Gate after strengthening when ambiguity remains — ask one question at a time, no upper limit
  • Read relevant code before asking a clarification question — asking answerable questions wastes the user's time
  • Apply the measurability test to every constraint added: "Can a reviewer objectively verify this was followed?"
  • Guardrail 2 (Intent Preservation) is a hard contract — a rewrite that changes the user's action verb, target, or output type is invalid
  • Critical-severity fixes are never subject to the 5-fix cap
  • Present the batch table when resource CRUD is detected, and wait for explicit user approval before creating, updating, or deleting
  • Delegate resource creation to the existing authoring tools (/writing-skills, /claude-guardian, skill-author agent) rather than generating directly
  • Optional one-line skill hint at the end of STEP 4.6: when the strengthened prompt clearly fits a workflow other than direct execution, append ONE italic line naming up to 2 relevant skills, with a quoted fragment from the user's prompt for each. Informational only — never gating, never numbered, never selectable. The auto-enhance skill's job is prompt enhancement, not execution routing. Skip the hint entirely on direct/mechanical/bug-fix/factual-lookup/documentation prompts and on prompts that already name a skill explicitly.

Anti-Patterns

These are common ways the pipeline goes wrong.

  • Strengthening direct unambiguous instructions — respect explicit user intent
  • Adding complexity during strengthening that doesn't map to a diagnosed weakness
  • Changing the user's original intent during strengthening — clarify and constrain only
  • Exceeding the max non-Critical changes cap (5) without explicit user request
  • Creating, updating, or deleting resources without batch approval
  • Re-prompting for items the user already rejected in the same session
  • Web searching when local context is sufficient — read code first
  • Generating patterns directly instead of using /writing-skills, /claude-guardian, or skill-author
  • Suggesting resource changes when CRUD signals are ambiguous — default to no CRUD
  • Hiding the step transcript or final prompt preview to save tokens — these are non-optional
  • Turning the optional skill hint into a numbered menu, selection prompt, or routing decision — the hint is text, not UI. The auto-enhance skill enhances prompts; it does not route execution.
  • Generic skill hints without a quoted fragment from the user's prompt — every appended hint must cite the strongest single matched fragment, same as the Clarification Gate.
  • Appending a hint on direct/mechanical/bug-fix/factual-lookup/documentation prompts where the user clearly wants direct action — adds friction with no value.
  • Suggesting more than 2 skills in a single hint — past 2, it stops being a hint and starts being a menu.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.