@event4u/agent-config 9.12.0 → 9.13.0

package/dist/agent-src/rules/design-fidelity.md

@@ -9,10 +9,21 @@ triggers:
   - keyword: "design system"
   - keyword: "design spec"
   - keyword: "Figma"
+  - keyword: "handoff"
+  - keyword: "Claude Design"
   - phrase: "match the design"
   - phrase: "build this design"
   - phrase: "design fidelity"
   - phrase: "stick to the design"
+  - phrase: "design.html"
+  - phrase: "attached artifact"
+  - phrase: "provided artifact"
+  - phrase: "übernimm das design"
+  - phrase: "baue das nach"
+  - phrase: "bau das nach"
+  - phrase: "1:1 um"
+  - phrase: "1:1 nach"
+  - file_pattern: "*design.html"
 applies_to_user_types:
   - "creator"
   - "developer"
@@ -73,6 +84,24 @@ porting, or modifying UI to match it.
 - The user explicitly invites exploration ("show me options", "redesign this", "improve the layout") — that authorises deviation for that turn.
 - Non-UI surfaces (scripts, CLI, backend).
 
+## Routing — an attached artifact is a trigger, an attached HTML file is not
+
+Matching is plain lower-cased substring containment on the prompt, plus fnmatch
+over the open files. Three handover classes must reach this rule: an English
+phrasing, a German one, and a prompt carrying **no** keyword at all because the
+artifact is simply attached. The last is covered by `file_pattern: *design.html`
+— the conventional handover filename, not `*.html`, which would fire on every
+HTML edit in every project and be strictly worse than the gap it closes. A
+handover under some other filename needs one word in the prompt.
+
+The trigger set is deliberately phrase-heavy on the German side and on
+`artifact`: a bare `artifact` keyword fires on "the CI build artifact is 40 MB".
+`ROUTING_MATRIX` in
+[`design_fidelity_routing.test.ts`](../../tests/scripts/design_fidelity_routing.test.ts)
+pins both halves — every class that must route, and the near-misses that must
+stay silent (fixture `daf-port-trigger-de`). Extending the set without adding a
+near-miss row there is how an over-broad trigger lands.
+
 Body migrated to [`guideline:design-fidelity-mechanics`](../docs/guidelines/design-fidelity-mechanics.md) (per P4 of `road-to-kernel-and-router.md`) — surgical visual edits (targeted-edit vs redesign-trigger discipline, stable anchors), asset & imagery discipline (owned-asset path, third-party delivery is self-hosted by default, real-imagery-as-proof, iconography floor, no unrequested filler), deviation-surfacing shape, failure-mode catalog, `daf-*` fixtures.
 Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).
 

package/dist/agent-src/rules/domain-adoption-policy.md

@@ -4,9 +4,6 @@ tier: "2b"
 alwaysApply: false
 description: "Adopting a new domain track (mobile, ML, IoT…) — demand/owner/CI gates BEFORE harvest"
 triggers:
-  - intent: "adopt new domain"
-  - intent: "harvest new domain track"
-  - intent: "open a domain plate"
   - keyword: "mobile track"
   - keyword: "ml track"
   - keyword: "blockchain track"

package/dist/agent-src/rules/downstream-changes.md

@@ -4,7 +4,6 @@ tier: "2b"
 alwaysApply: false
 description: "After EVERY code edit, find ALL downstream changes — callers, tests, imports, types, documentation"
 triggers:
-  - intent: "after code edit"
   - keyword: "callers"
   - keyword: "imports"
   - keyword: "downstream"
@@ -81,6 +80,16 @@ Next.js / Python / Go) live in [`agent-docs-writing`](../skills/agent-docs-writi
 Before making a change that affects a **public API** (endpoint response, service method signature,
 event payload, job constructor), assess the impact:
 
+**Why the surface, not just the contract, is the thing to keep small** (Hyrum's
+Law): with enough consumers, every *observable* behaviour of a system becomes
+something somebody depends on, regardless of what the documented contract
+promises — iteration order, an error message's wording, a timing side effect, a
+field that happens to be present. Two consequences, and they point in opposite
+directions. Adding: a smaller exported surface is fewer accidental contracts to
+honour later, so do not export what the caller does not need. Removing: the
+list above is a floor, not a ceiling — an observable behaviour nobody documented
+can still break someone when it disappears.
+
 ### Always ask the user first when:
 
 - Removing or renaming a public method/class

package/dist/agent-src/rules/external-reference-deep-dive.md

@@ -4,13 +4,6 @@ tier: "2b"
 description: "User names an external repo/file/URL as reference — fetch the actual tree and inspect; never summarize from README"
 alwaysApply: false
 triggers:
-  - intent: "look at how X does it"
-  - intent: "compare with reference repo"
-  - intent: "use as template / vorlage"
-  - intent: "wie macht es X"
-  - intent: "vergleiche mit Y"
-  - intent: "schau dir Z an"
-  - intent: "study this competitor"
   - keyword: "github.com/"
   - keyword: "source of truth"
   - phrase: "reference repo"

package/dist/agent-src/rules/fast-path-marker-visibility.md

@@ -7,7 +7,6 @@ triggers:
   - keyword: "fast-path"
   - keyword: "Resolved via low-impact council"
   - keyword: "low_impact"
-  - intent: "low-impact council dispatch"
 validator_ignore:
   - type: "substring"
     pattern: ".agent-src.uncondensed/"

package/dist/agent-src/rules/git-history-discipline.md

@@ -4,13 +4,6 @@ tier: "2a"
 alwaysApply: false
 description: "Git history — no unasked rebase/squash/amend; never drop foreign commits; pushed rewrite → re-push same turn"
 triggers:
-  - intent: "rebase the branch"
-  - intent: "squash commits"
-  - intent: "clean up commit history"
-  - intent: "fold this into the previous commit"
-  - intent: "tidy history after pushing"
-  - intent: "reseat the branch base"
-  - intent: "exclude these commits from the branch"
   - keyword: "git rebase"
   - keyword: "rebase --onto"
   - keyword: "reset --hard"

package/dist/agent-src/rules/guidelines.md

@@ -6,8 +6,6 @@ alwaysApply: false
 load_context:
   - ../contexts/communication/rules-auto/guidelines-mechanics.md
 triggers:
-  - intent: "writing code"
-  - intent: "reviewing code"
   - keyword: "convention"
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]

package/dist/agent-src/rules/improve-before-implement.md

@@ -5,8 +5,6 @@ description: "Before features or architectural changes — validate against exis
 alwaysApply: false
 council_depth: deep
 triggers:
-  - intent: "implement feature"
-  - intent: "architectural change"
   - keyword: "refactor"
   - keyword: "implement"
   - keyword: "migration"
@@ -42,6 +40,10 @@ Before implementing:
 
 On a "build me an app / add this feature" ask, ONE reflexive pre-check before the three checks: **who asked · what breaks if unbuilt · what's the evidence?** Recommend **build** only at a real retention/activation blocker (evidence, not anxiety); else **defer/validate**, naming the missing evidence. Advisory — "just build it" proceeds immediately; no network lookup. Hierarchy + build/defer table: guideline § 8-pre.
 
+## The solution-size ladder — stop at the first rung that works
+
+Once the demand gate says build, "does this already exist?" has an **ordered** answer set: need-to-exist → reuse-in-repo → stdlib / framework → **native platform** → installed dependency → smallest working form. Stop at the first rung that carries the requirement. Ordered **after** comprehension — it shortens the solution, never the reading. Two axes, not one: the ladder is *scope*; **shape** is the other half — of what must exist, the form with the least cognitive load, explicitly not the fewest keystrokes. Rungs, the platform-rung examples, and the precedence order when they pull against each other: guideline § 8b-ladder / § 8b-shape / § 8b-precedence.
+
 ## The three checks
 
 Run, in order: **1. Is the request clear?** · **2. Does it fit the existing architecture?** · **3. Is the approach sound?**

package/dist/agent-src/rules/invite-challenge.md

@@ -5,10 +5,6 @@ description: "Before executing a complex plan — ask 'am I solving the right pr
 alwaysApply: false
 council_depth: deep
 triggers:
-  - intent: "complex plan"
-  - intent: "design decision"
-  - intent: "architectural plan"
-  - intent: "multi-step implementation"
   - keyword: "plan"
   - keyword: "design"
   - keyword: "architecture"

package/dist/agent-src/rules/linked-projects-onboarding-gate.md

@@ -4,8 +4,6 @@ tier: "2b"
 alwaysApply: false
 description: "IDE-attached sibling repo detected — prompt once to opt into cross-repo awareness, persist local-only"
 triggers:
-  - intent: "work across two projects"
-  - intent: "sibling repository"
   - keyword: "linked project"
   - keyword: "cross-repo"
   - keyword: "sibling repo"

package/dist/agent-src/rules/markdown-safe-codeblocks.md

@@ -4,7 +4,6 @@ tier: "2b"
 description: "Generating markdown with code blocks — prevent broken nesting"
 alwaysApply: false
 triggers:
-  - intent: "markdown with code blocks"
   - keyword: "triple backticks"
   - file_pattern: "*.md"
 workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]

package/dist/agent-src/rules/minimal-safe-diff.md

@@ -4,11 +4,11 @@ tier: "2a"
 alwaysApply: false
 description: "Writing or reviewing a diff — smallest change that solves the problem; no drive-by edits or reformatting"
 triggers:
-  - intent: "writing a diff"
-  - intent: "reviewing a diff"
   - keyword: "drive-by"
   - keyword: "rewrite"
   - keyword: "fix"
+  - phrase: "from scratch"
+  - phrase: "second system"
 routes_to:
   - "guideline:agent-infra/minimal-safe-diff-mechanics"
 workspaces: [engineering]

package/dist/agent-src/rules/missing-tool-handling.md

@@ -5,7 +5,6 @@ description: "CLI tool needed for the task is not installed — ask before worki
 triggers:
   - keyword: "command not found"
   - keyword: "not installed"
-  - intent: "install tool"
 routes_to:
   - "guideline:agent-infra/missing-tool-handling"
 workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]

package/dist/agent-src/rules/no-attribution-footers.md

@@ -4,9 +4,6 @@ tier: "3"
 alwaysApply: false
 description: "PR/issue/comment/commit bodies — no 'Generated with' / 'Co-authored by' / 'opened by' attribution footers"
 triggers:
-  - intent: "PR body"
-  - intent: "commit message"
-  - intent: "Jira comment"
   - keyword: "co-authored"
 workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
 packs: [meta]

package/dist/agent-src/rules/no-decorative-emojis-in-git-surfaces.md

@@ -4,13 +4,16 @@ tier: "3"
 alwaysApply: false
 description: "PR/issue/commit titles and comments — no decorative emojis; bodies only with an in-artifact legend"
 triggers:
-  - intent: "PR title"
-  - intent: "PR body"
-  - intent: "commit message"
-  - intent: "issue title"
-  - intent: "post PR comment"
   - keyword: "gh pr create"
   - keyword: "git commit"
+  - keyword: "🤖"
+  - keyword: "🚀"
+  - keyword: "🎉"
+  - keyword: "✨"
+  - keyword: "🔥"
+  - keyword: "💡"
+  - keyword: "👍"
+  - keyword: "❤️"
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
 ---

package/dist/agent-src/rules/no-pr-progress-comments.md

@@ -4,11 +4,9 @@ tier: "2a"
 alwaysApply: false
 description: "PR comments — no unsolicited progress/status/CI narration unless personal.pr_progress_comments is true"
 triggers:
-  - intent: "post PR comment"
-  - intent: "PR status update"
-  - intent: "CI fix progress"
   - keyword: "gh pr comment"
   - keyword: "PullRequestComment"
+  - phrase: "status comment"
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
 ---

package/dist/agent-src/rules/no-roadmap-references.md

@@ -8,8 +8,6 @@ triggers:
   - path_prefix: "agents/runtime/council/questions/"
   - path_prefix: "agents/runtime/council/responses/"
   - path_prefix: "agents/runtime/council/sessions/"
-  - intent: "link from stable artifact"
-  - intent: "link to council artefact"
 routes_to:
   - "skill:ai-council"
   - "skill:agent-docs-writing"

package/dist/agent-src/rules/output-discipline.md

@@ -3,7 +3,6 @@ type: "auto"
 tier: "2a"
 description: "No placeholder prose in generated code/UI — no truncation shorthands; on budget overflow emit a clean PAUSED breakpoint"
 triggers:
-  - intent: "generating code or multi-section output"
   - keyword: "// rest of component"
   - keyword: "for brevity"
   - keyword: "rest follows the same pattern"

package/dist/agent-src/rules/prefer-enums-over-literals.md

@@ -4,8 +4,6 @@ tier: "2b"
 alwaysApply: false
 description: "Field with multiple non-boolean states — prefer an enum over string/numeric literals; old-style literals found → note, finish the task, ask after"
 triggers:
-  - intent: "modeling a field with multiple states"
-  - intent: "adding a status or type field"
   - keyword: "enum"
   - keyword: "status"
   - keyword: "kind"

package/dist/agent-src/rules/preservation-guard.md

@@ -4,9 +4,6 @@ tier: "2b"
 alwaysApply: false
 description: "Merging/refactoring/condensing skills, rules, commands, or guidelines — prevent quality loss"
 triggers:
-  - intent: "merge skill"
-  - intent: "condense rule"
-  - intent: "refactor artifact"
   - keyword: "Iron Law"
 validator_ignore:
   - type: "substring"

package/dist/agent-src/rules/role-mode-adherence.md

@@ -6,7 +6,6 @@ alwaysApply: false
 triggers:
   - keyword: "active_role"
   - keyword: "role-mode"
-  - intent: "mode marker"
 workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
 packs: [meta]
 ---

package/dist/agent-src/rules/secret-vcs-guard.md

@@ -4,8 +4,6 @@ tier: "2a"
 alwaysApply: false
 description: "Writing a credential into a tracked file or committing one in any VCS (git/svn/hg) — STOP, show the match, ask, offer alternatives; never silently"
 triggers:
-  - intent: "writing a credential or API key into a file"
-  - intent: "committing or staging changes that may contain a secret"
   - keyword: "secret"
   - keyword: "password"
   - keyword: "credential"

package/dist/agent-src/rules/senior-engineering-discipline.md

@@ -4,8 +4,6 @@ tier: "2b"
 alwaysApply: false
 description: "Writing/generating code — generalize (no overfit/tautological tests), supply the invisible cross-cutting controls, never invent an API/field/package"
 triggers:
-  - intent: "writing or generating code"
-  - intent: "implementing a feature"
   - keyword: "implement"
   - keyword: "endpoint"
   - keyword: "query"

package/dist/agent-src/rules/session-canary.md

@@ -4,8 +4,6 @@ tier: "2a"
 description: "personal.canary_name set — open every new task by name (liveness canary); keep the reply-close markers alive (ONE end-summary, PR URL last)"
 alwaysApply: false
 triggers:
-  - intent: "starting a new task or a new conversation"
-  - intent: "opening the first reply to a request"
   - keyword: "canary"
   - keyword: "canary_name"
   - phrase: "session canary"

package/dist/agent-src/rules/size-enforcement.md

@@ -3,11 +3,6 @@ type: "manual"
 tier: "mechanical-already"
 description: "Creating or editing rules, skills, commands, guidelines, AGENTS.md, or copilot-instructions.md — enforce size and scope limits"
 alwaysApply: false
-triggers:
-  - intent: "create rule"
-  - intent: "create skill"
-  - intent: "create command"
-  - intent: "create guideline"
 workspaces: [agent-config-maintainer]
 packs: [meta]
 ---

package/dist/agent-src/rules/source-confidentiality.md

@@ -10,9 +10,6 @@ triggers:
   - path_prefix: "docs/"
   - path_prefix: "agents/evidence/"
   - path_prefix: "agents/roadmaps/"
-  - intent: "adopt or harvest from an external repo"
-  - intent: "compare against another package"
-  - intent: "attribute an idea to an external source"
 validator_ignore:
   - type: "substring"
     pattern: "external_sources_denylist"

package/dist/agent-src/rules/source-discovery-gate.md

@@ -7,8 +7,6 @@ load_context:
   - ../contexts/execution/evidence-discipline.md
   - ../contexts/execution/project-intelligence.md
 triggers:
-  - intent: "before coding"
-  - intent: "DB-driven work"
   - keyword: "schema"
   - keyword: "endpoint"
   - phrase: "new API"

package/dist/agent-src/rules/think-before-action.md

@@ -6,9 +6,9 @@ alwaysApply: false
 load_context:
   - ../contexts/communication/rules-auto/think-before-action-mechanics.md
 triggers:
-  - intent: "before coding"
-  - intent: "before debugging"
-  - intent: "before modifying"
+  - phrase: "before coding"
+  - phrase: "before debugging"
+  - phrase: "before modifying"
   - keyword: "implement"
   - keyword: "debug"
   - keyword: "refactor"

package/dist/agent-src/rules/token-budget-discipline.md

@@ -5,7 +5,6 @@ description: "rich-class skills are exempt from telegraph + thin-projector trims
 triggers:
   - keyword: "token_budget_class"
   - keyword: "rich skill"
-  - intent: "editing a rich-tagged skill"
 workspaces: [agent-config-maintainer]
 packs: [meta]
 ---

package/dist/agent-src/rules/token-efficiency.md

@@ -6,9 +6,8 @@ alwaysApply: false
 load_context:
   - ../contexts/communication/rules-auto/token-efficiency-mechanics.md
 triggers:
-  - intent: "verbose CLI output"
-  - intent: "fetching logs"
   - keyword: "minimize tool calls"
+  - phrase: "fetching logs"
 workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
 packs: [meta]
 ---

package/dist/agent-src/rules/tool-safety.md

@@ -5,7 +5,6 @@ description: "Skill uses external tools — enforce allowlist, deny-by-default,
 triggers:
   - keyword: "allowed_tools"
   - keyword: "tool registry"
-  - intent: "external API"
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
 enforced_by:

package/dist/agent-src/rules/user-interaction.md

@@ -6,9 +6,6 @@ alwaysApply: false
 load_context:
   - ../contexts/communication/rules-auto/user-interaction-mechanics.md
 triggers:
-  - intent: "ask user a question"
-  - intent: "numbered options"
-  - intent: "summarizing progress"
   - keyword: "option"
   - keyword: "recommendation"
   - phrase: "what do you recommend"

package/dist/agent-src/rules/user-interrupt-priority.md

@@ -4,7 +4,6 @@ tier: "2a"
 description: "New user instruction mid-flight — STOP the current task, run the new one in full, ASK before resuming"
 alwaysApply: false
 triggers:
-  - intent: "new instruction while a task is running"
   - keyword: "weiter"
   - keyword: "resume"
   - keyword: "continue"

package/dist/agent-src/skills/agent-docs-writing/SKILL.md

@@ -237,6 +237,14 @@ numbered options; do NOT auto-rewrite prose without the user's knowledge:
 - Do NOT duplicate content that's already in `AGENTS.md` or `.github/copilot-instructions.md`.
 - Do NOT write docs just to document what you did — only document things others need to know.
 - If unsure whether a doc needs updating, **ask the user**.
+- **Sibling-routing sentences are edited as a set, never alone.** When a skill's
+  `description:` carries a routing clause naming an overlapping sibling
+  (`Animated → pixar-storyteller`), editing it obliges re-reading every sibling
+  it names and every sibling that names it, so no user phrase ends up routed to
+  two skills and none ends up routed to neither. One-sided edits are how a
+  cluster's descriptions drift back into ambiguity between sweeps;
+  `lint_skill_descriptions` catches a *missing* clause, not an *inconsistent*
+  one.
 
 ## Output format
 

package/dist/agent-src/skills/analysis-skill-router/SKILL.md

@@ -11,6 +11,11 @@ packs:
 
 # analysis-skill-router
 
+A chooser, not a worker. It answers exactly one question — *which skill* — and
+then gets out of the way. How to actually carry out the work belongs to
+whichever skill this picks; a chooser that also explains the work reads like
+its own fallback target, which is the defect this file was cut back from.
+
 ## When to use
 
 Use this skill when:
@@ -29,111 +34,75 @@ Do NOT use when:
 
 ## Procedure
 
-### 1. Identify request scope
-
-Classify the request as one of:
-
-* full project analysis
-* architecture review
-* broad multi-layer debugging
-* framework-specific deep analysis
-* narrow root-cause analysis
-* performance/security specialist analysis
-* simple local code issue
-
-### 2. Check whether deep analysis is justified
-
-Use deep analysis only if at least one is true:
-
-* the user explicitly asks for broad analysis
-* the system is unclear or unknown
-* the issue spans multiple layers
-* architecture reconstruction is required
-* the cause is not local and not obvious
-
-If none apply → do NOT route to a broad analysis skill.
-
-### 3. Detect framework or system type
-
-Check whether the request clearly targets:
-
-* Laravel, Symfony, Zend/Laminas, Node/Express, React, Next.js
-* unknown / mixed stack
-
-### 4. Route to the correct skill
+### 1. Classify the scope
 
-#### Broad / unknown system
+Pick one: full project · architecture review · broad multi-layer debugging ·
+framework-specific deep dive · narrow root cause · performance/security
+specialist · simple local issue.
 
-* full project analysis or unclear stack → `universal-project-analysis`
-* unknown system, discovery-focused → `project-analysis-core`
+**Broad scope requires a reason.** At least one must hold, or the answer is a
+narrow specialist: the user asked for breadth · the system is unknown · the
+issue spans layers · architecture must be reconstructed · the cause is
+non-local.
 
-#### Root-cause analysis
+### 2. Detect the framework
 
-* concrete multi-cause problem → `project-analysis-hypothesis-driven`
-* bug-focused but not full-project → `bug-analyzer`
+Laravel · Symfony · Zend/Laminas · Node/Express · React · Next.js · unknown or
+mixed.
 
-#### Backend framework analysis
+### 3. Read the decision table
 
-* Laravel → `project-analysis-laravel`
-* Symfony → `project-analysis-symfony`
-* Zend/Laminas → `project-analysis-zend-laminas`
-* Node/Express → `project-analysis-node-express`
+| Signal | Route to |
+|---|---|
+| Full audit, or unclear stack | `universal-project-analysis` |
+| Unknown system, discovery-focused | `project-analysis-core` |
+| Concrete problem, several plausible causes | `project-analysis-hypothesis-driven` |
+| Bug-focused, not full-project | `bug-analyzer` |
+| Laravel | `project-analysis-laravel` |
+| Symfony | `project-analysis-symfony` |
+| Zend/Laminas | `project-analysis-zend-laminas` |
+| Node/Express | `project-analysis-node-express` |
+| React state / render / hooks | `project-analysis-react` |
+| Next.js SSR / cache / hydration | `project-analysis-nextjs` |
+| Bottleneck | `performance-analysis` |
+| Security concern | `security-audit` |
 
-#### Frontend / rendering analysis
-
-* React state/render/hooks issues → `project-analysis-react`
-* Next.js SSR/client/cache/hydration issues → `project-analysis-nextjs`
-
-#### Specialist follow-up routing
-
-* performance bottleneck → `performance-analysis`
-* security concern → `security-audit`
-
-### 5. Validate routing quality
-
-Check:
-
-* the chosen skill is narrower than the broadest possible option
-* full-project analysis is actually justified if selected
-* framework-specific skill matches the explicit framework
-* no simpler specialist skill was skipped
+Tie-break: **the narrowest row that still covers the request wins.**
 
 ## Output format
 
-1. Selected skill
-2. Reason for selection
-3. Why broader alternatives were not chosen
-4. Optional chained specialist skills
-
-## Routing heuristics
-
-**Choose `universal-project-analysis` only if:** user explicitly wants full audit, architecture must be reconstructed, stack is unclear, multiple subsystems involved.
-
-**Choose `project-analysis-core` if:** broad discovery needed, framework deep-dive not yet justified.
-
-**Choose `project-analysis-hypothesis-driven` if:** problem is concrete, multiple causes plausible, main job is explanation not discovery.
-
-**Choose framework-specific analysis if:** framework is explicit, failure pattern is framework-shaped.
+1. The selected skill.
+2. The signal from step 1–2 that selected it.
+3. Why the next-broader row lost, when one was plausible.
+4. Any skill to chain afterwards — or "none".
 
-**Do NOT route broadly if:** one component or file is enough, fix is obvious and local, task is implementation not investigation.
+One or two lines total. A routing verdict longer than the request it routes is
+itself a routing failure.
 
 ## Examples
 
-**"Analyze this whole Laravel project"** → `universal-project-analysis` → chain `project-analysis-laravel`
-**"Hydration mismatch in Next.js"** → `project-analysis-nextjs` (no full-project needed)
-**"Bug could be cache, queue, or version mismatch"** → `project-analysis-hypothesis-driven`
-**"Change one React component"** → no analysis skill, use implementation skill
+| Request | Route |
+|---|---|
+| "Analyze this whole Laravel project" | `universal-project-analysis`, chain `project-analysis-laravel` |
+| "Hydration mismatch in Next.js" | `project-analysis-nextjs` — no full-project step |
+| "Could be cache, queue, or a version mismatch" | `project-analysis-hypothesis-driven` |
+| "Change one React component" | none — implementation skill |
 
 ## Gotcha
 
-* The most expensive skill is often not the best skill.
-* Broad analysis feels safe but reduces sharpness when the problem is already localized.
-* Framework-specific routing should happen as early as possible once the framework is explicit.
+* **Size adjectives read as scope.** "Our *whole* Laravel app is slow" picks the
+  broad row on the word "whole", and the audit then spends its passes
+  rediscovering a stack the request already named. The step-2 framework signal
+  outranks size words — those are how frustration sounds, not scope.
+* **Breadth feels safe and costs sharpness.** The most expensive choice is
+  rarely the best one once the problem is already localised.
+* **Steps 1 and 2 disagreeing is a question, not a tie-break.** Ask which the
+  user meant instead of picking the broader row to be safe.
 
 ## Do NOT
 
 * Do NOT default to `universal-project-analysis`
-* Do NOT use full-project analysis for normal feature work
-* Do NOT choose a generic skill when a framework-specific one clearly fits
-* Do NOT route to deep analysis when a simple specialist skill is enough
+* Do NOT choose a generic skill when a framework-specific row fits
 * Do NOT confuse discovery with root-cause investigation
+* Do NOT re-import procedure, validation checklists, or output contracts from
+  the skills in the table — that is what this file was cut back from