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.
In this repository44 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- anthropic-multi-agent-research-system-skillSkill
- apply-selectionsSkill
- bootstrap-dogfood-projectSkill
- brainstormSkill
- branch-choiceSkill
- cc-adoption-scoutSkill
- claude-guardianSkill
- continueSkill
- end-sessionSkill
- executing-plansSkill
- five-advisorsSkill
- get-work-doneSkill
- git-branch-lifecycleSkill
- githubSkill
- grill-meSkill
- hook-transcript-fixture-testSkill
- instagramSkill
- linkedinSkill
- modern-data-pipeline-diagramSkill
- pattern-qualitySkill
- platform-event-live-probeSkill
- plugin-lifecycleSkill
- promote-to-coreSkill
- provision-reportSkill
- redditSkill
- review-new-claude-featuresSkill
- save-sessionSkill
- scan-discovery-reportSkill
- scan-repoSkill
- scan-urlSkill
- self-improveSkill
- skill-evaluatorSkill
- skill-masterSkill
- ssot-workflow-auditSkill
- start-sessionSkill
- synthesize-hubSkill
- synthesize-projectSkill
- twitter-xSkill
- verify-effect-at-destinationSkill
- workflow-doc-reviewerSkill
- writing-plansSkill
- writing-skillsSkill
- youtube-transcriptSkill
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
- Very specific: line 93
Load-bearing test: if the misheard word changes WHAT gets built (two plausible readings diverge materially), do NOT guess — route it to the …
- Distinctive: line 138
Every score in [1.0, 10.0] now maps to exactly one grade.
- Distinctive: line 171
No quote → no override; "could be better" never qualifies.
- Very specific: line 206
Policy: never skip MISSING_ROLE: When Role dim < 7, always add a task-class-appropriate role to the strengthened prompt.
- Distinctive: line 246
If no row matches, synthesize a role using this skeleton:
- Distinctive: line 265
Always one role, not a list of options.
- Distinctive: line 272
Always task-class appropriate — generic "AI assistant" framing is never the answer when Role < 7.
- Distinctive: line 276
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 …
- Distinctive: line 279
If the user's prompt explicitly contradicts a default role (e.g., "be casual" against a formal-default class), the user wins.
- Distinctive: line 283
Never ship a default qualifier that contradicts the persona — a wrong audience frame is worse than no role at all (observed failure: a …
- Distinctive: line 289
Use XML tags when prompts mix instructions, context, data, and constraints (3+ distinct parts).
- Distinctive: line 291
Use 3-7 tags max — over-tagging adds noise.
- Very specific: line 306
After category diagnosis, scan for words and phrases that weaken instruction clarity.
- Distinctive: line 342
Pruning rule: every removal improves precision.
- Distinctive: line 346
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 …
- Distinctive: line 381
Every rewrite preserves: same action verb, same target, same output type, no new requirements added beyond what the user implied.
- Distinctive: line 394
Check for contradictions between added constraints
- Distinctive: line 399
Add complexity only when it directly eliminates a diagnosed weakness
- Distinctive: line 400
Keep terminology the user chose unless it causes ambiguity
- Distinctive: line 401
Remove qualifiers and hedging language flagged in Step 1
- Distinctive: line 413
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, …
- Very specific: line 425
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 … - Very specific: line 468
EVERY turn (STEP 3.6); its Reviewer-after column IS its grade card.
- Distinctive: line 470
ALWAYS print the "Independent reviewer" line stating who it is and what it did.
- Distinctive: line 504
Grade D warning line (locked format): when the prompt graded D, render this line ABOVE the grade card — the "heavy warning" is this exact …
- Very specific: line 518
Update the *Enhanced:* indicator to include strengthening: *Enhanced: prompt strengthened (N fixes, Grade X), git state, 2 rules*
- Distinctive: line 551
If the user wants per-dimension scores, they're in Step 4.
- Very specific: line 597
OVER_SCOPED rendering: when Step 3 split the prompt into sequential focused sub-prompts, the Final block contains the numbered sequence — …
- Very specific: line 612
When the strengthened prompt clearly fits a workflow other than direct execution (e.g., a high-stakes decision benefits from …
- Very specific: line 686
If the turn produced committable changes, dispatch git-manager-agent to stage → secret-scan → commit (conventional + the Co-Authored-By …
- Distinctive: line 721
No after-card renders on a grill turn — there is no strengthened prompt to re-grade yet.
- Distinctive: line 732
Question budget: no upper limit. Ask one question at a time and keep asking until you have full confidence in the user's intent.
- Distinctive: line 739
Read the codebase before asking — do not ask what you can answer yourself
- Distinctive: line 767
If you can't cite one, you don't have enough context to recommend yet — read more code first instead of asking.
- Distinctive: line 790
Quote-as-evidence: every dimension score cites a specific phrase from the prompt that justifies it.
- Distinctive: line 792
Use case input: ask the user to describe the prompt's use case before scoring.
- Distinctive: line 809
When the global rule detects that a user's prompt implies creating, updating, or deleting Claude Code resources (skills, agents, rules, …
- Distinctive: line 881
CRUD Exception: when creating/updating a resource targeting an external technology, search the web for current docs — training data may be …
- Distinctive: line 930
When in doubt, default to NO CRUD — do not suggest resource changes unless the signals are clear.
- Very specific: line 939
Run STEP 0 (Quick Grade) before any diagnosis, and skip diagnosis for Grade A — with ONE exception: the cap-exempt MISSING_ROLE fix applies …
- Distinctive: line 943
Run the Clarification Gate after strengthening when ambiguity remains — ask one question at a time, no upper limit
- Distinctive: line 944
Read relevant code before asking a clarification question — asking answerable questions wastes the user's time
≈ “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.
Files
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.
| Mode | Banner + grade card + reviewer + final-prompt | Stop-hook enhance enforcement | Governance tail |
auto (default) | rendered every substantive turn | on (reviewer-card + diagnosis blocks) | on |
ask | suppressed; append one line "Enhance available — reply enhance…" | off | on |
off | suppressed entirely | off | on |
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:
- Strip fillers/stutters/restarts silently (they carry no meaning).
- For each phonetic mishear, render a visible mapping line so the
interpretation is auditable:
heard: "<verbatim>" → read as: "<term>" (<phonetic|context> match) - 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. - STEP 0 grades the NORMALIZED text; STEP 4.6 still shows the user's ORIGINAL verbatim (the mapping lines bridge the two).
- 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.
| Dimension | Default Weight | Weight w/ Tone Active | Measures |
| Intent Clarity | 0.25 | 0.25 | Action verb + target + success criteria explicit |
| Context Sufficiency | 0.20 | 0.20 | All needed background present |
| Constraint Precision | 0.20 | 0.20 | Boundaries measurable and unambiguous |
| Output Specification | 0.15 | 0.15 | Expected result format defined |
| Role & Framing | 0.10 | 0.05 | Persona, domain, expertise level |
| Example Grounding | 0.10 | 0.05 | Input/output examples for complex tasks |
| Tone Consistency | 0.00 | 0.10 | Voice/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:
| Grade | Range | Action |
| A | ≥ 8.0 | Skip 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.0 | Suggested 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):
- Intent Clarity OR Context Sufficiency scoring 1-2 → Grade F
- More than 5 Critical issues diagnosed → Grade F
- Any other single dimension scoring 1-2 → cap at Grade B (max 7.9)
- Otherwise → use the threshold table above
Dimension-to-Category mapping:
| Dimension < 7 | Diagnose These Categories |
| Intent Clarity | VAGUE_INTENT, AMBIGUOUS_SCOPE |
| Context Sufficiency | MISSING_CONTEXT, IMPLICIT_ASSUMPTIONS |
| Constraint Precision | UNDER_CONSTRAINED, CONFLICTING_CONSTRAINTS |
| Output Specification | MISSING_OUTPUT_SPEC, MISSING_STRUCTURE |
| Role & Framing | MISSING_ROLE |
| Example Grounding | MISSING_EXAMPLES |
| Tone Consistency | MISSING_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
| Category | Severity | Symptoms | Structural Fix |
| VAGUE_INTENT | Critical | Unclear what the user wants done; could be interpreted multiple ways | Rewrite as specific action verb + object + success criteria |
| MISSING_CONTEXT | Critical | Prompt assumes knowledge not provided (file paths, prior decisions, domain terms) | Add explicit context: which files, which module, what prior state |
| CONFLICTING_CONSTRAINTS | High | Prompt asks for contradictory things ("make it fast and thorough") | Identify the conflict, prioritize one, note the tradeoff |
| OVER_SCOPED | High | Asks for too many things at once; would require 5+ files changed | Break into sequential focused prompts, suggest ordering |
| UNDER_CONSTRAINED | Medium | Vague 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_SPEC | Medium | No indication of what the result should look like | Add a locked output template with named sections, explicit order, numeric length bounds (see references/format-locking.md) |
| AMBIGUOUS_SCOPE | Medium | Unclear which files, modules, or layers are in scope | Add explicit scope boundaries ("only in src/api/", "just the tests") |
| IMPLICIT_ASSUMPTIONS | Low | Prompt relies on assumptions that may not hold (env setup, dependencies, prior steps) | Make assumptions explicit or add verification steps |
| MISSING_STRUCTURE | Low | Multi-part prompt uses flat unstructured text where XML tags would improve clarity | Restructure with XML tags (see XML Tag Reference below) |
| MISSING_ROLE | Medium | No explicit persona or domain frame (Role dim < 7) | Always add a task-class-appropriate role using the "Role Selection Guide" below — never skip |
| MISSING_EXAMPLES | Low | No input/output examples for complex tasks | Add 2-3 diverse examples in <examples> tags |
| MISSING_TONE_FRAME | Medium (Tone-active prompts only) | No voice, register, or audience guidance for prose output | Add tone spec: register (formal/casual), audience, length bounds, voice attributes |
Severity handling:
| Severity | Behavior |
| Critical | Always included — Critical fixes are never capped |
| High | Included up to the max changes cap |
| Medium | Included up to the max changes cap |
| Low | Included 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 class | Detection signals | Default role |
| Mechanical execution | rename, 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 implementation | implement, 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 retrieval | what 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 — security | review, 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 — perf | review, 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 — accessibility | review, 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 design | design, 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 design | design, 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 modeling | design, 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/UX | write, 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 strings | write, 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 copy | write, 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 docs | write, 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 support | should 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 / adaptation | rewrite 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 investigation | debug, 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 Pattern | Problem | Replace With |
| "try to", "attempt to" | Permits failure as acceptable | Direct imperative ("do X") |
| "if possible", "when feasible" | Creates an opt-out clause | Remove, or state the specific condition |
| "maybe", "perhaps", "might" | Introduces uncertainty into instructions | Commit to a direction or use conditional logic |
| "I think", "I believe" | Weakens authority of the instruction | State the requirement directly |
| "please", "kindly" | Politeness filler in technical prompts | Remove — instructions are not requests |
| "etc.", "and so on", "and more" | Unbounded scope | List all items explicitly |
| "simple", "just", "easily" | Minimizes complexity, sets false expectations | Remove — let the task speak for itself |
| "as needed", "as appropriate" | Delegates decision without criteria | Specify the criteria for when/how |
| "feel free to" | Implied optionality for required behavior | Remove |
| "don't worry about" | Unclear exclusion scope | State what TO do |
| "roughly/approximately" (when precision needed) | Vague threshold where exact value matters | State exact threshold |
Category B — Aggressive Enforcement Anti-Patterns (Claude 4.x specific)
| Flag Pattern | Problem | Replace With |
| "CRITICAL:/IMPORTANT:/YOU MUST" | Aggressive emphasis degrades compliance in newer models | Normal directive |
| "NEVER EVER/ABSOLUTELY MUST" | Over-emphatic phrasing triggers resistance | Standard 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 Pattern | Problem | Replace With |
| "Certainly!/Of course!/Absolutely!" | Sycophantic opener wastes tokens | Lead with the answer |
| "Based on the information provided..." | Filler preamble | Remove |
| "I'd be happy to help with..." | Unnecessary pleasantry | Remove |
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 descriptionSTEP 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.
| Original | Rewritten | Verdict | |
| 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 specFull 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:
| Condition | Action |
| 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 command | Skip 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-docswhen 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:
- STEP 0-3: grade, diagnose, rewrite (internal)
- STEP 4: show grade card + Changes Applied (metadata only — no prompt text)
- Clarification & Confidence Gate (if ambiguity/consequential fork remains — ask one question, or
/grill-mefor a consequential fork under ~95% confidence) - STEP 4.5: show step transcript (counts and deltas only — no per-dim or per-fix lists)
- 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)
- STEP 4.7: state
Role: <name> — <why>and dispatch its agents/skills (engineering-roles.md) - STEP 5: execute the strengthened prompt under decision-authority (decide reversible; escalate irreversible in one line)
- 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:
- Quote-as-evidence: every dimension score cites a specific phrase from the prompt that justifies it. Score with no quote → invalid.
- 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.
- 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 itemnone— reject everything, proceed with the original prompt normally1,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 Type | Delegate To | How |
| Skill | /writing-skills | Skill(skill="writing-skills") with the skill name and description |
| Rule | /claude-guardian | Skill(skill="claude-guardian") with the rule text |
| Agent | skill-author agent | Agent(prompt="Create agent: <description>", subagent_type="skill-author") |
| Hook | Manual workflow | Create 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)
| Source | What to Read | Why |
.claude/ patterns | Glob("core/.claude/{rules,skills,agents,hooks}/**") and Glob(".claude/{rules,skills,agents,hooks}/**") | Know what exists to avoid duplication |
| CLAUDE.md | Already loaded by system | Architecture, commands, conventions |
| Git state | git status, git log --oneline -5 | Current branch, recent work, uncommitted changes |
Tier 2 — Conditional
| Source | When to Read | What to Read |
| Nearby files | Prompt mentions a specific file/feature/module | Imports, dependencies, tests, related modules |
registry/patterns.json | Prompt involves pattern creation or comparison | Check 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-authoragent) 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, orskill-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.
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
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.

