From db0aa5d040788541e6923a8b1144a6fa504f3e88 Mon Sep 17 00:00:00 2001 From: notque Date: Sun, 10 May 2026 19:17:32 +0000 Subject: [PATCH] fix: positive-frame all agent and skill references for 100% joy-check compliance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fleet-wide sweep: 56 violations → 0 across 45 files. Mechanical fixes (22): Anti-Pattern headings → Common Failure Modes via expanded bulk_fix_instruction_joy.py SAFE_REWRITES dictionary. Editorial fixes (28): NEVER/Don't/Avoid/do NOT → positive action framing. Each rewrite preserves technical substance, changes only framing direction. Template fixes (high-severity violation generators): - agent-template.md: "Don't add features" → "Scope changes to what was requested" - preferred-patterns.md: NEVER/Do NOT in instructional prose → positive framing - skill-template.md: NEVER example in teaching table → positive alternative Infrastructure: - PHILOSOPHY.md added to validator allowlist (teaches patterns by example) - bulk_fix_instruction_joy.py: 6 → 28 safe rewrite entries - test expectations updated for new rewrite values --- agents/database-engineer/references/sql.md | 2 +- .../references/go-errors.md | 2 +- .../references/preferred-patterns.md | 2 +- .../references/metrics-and-monitoring.md | 2 +- .../references/python-errors.md | 2 +- .../references/preferred-patterns.md | 2 +- .../typescript-preferred-patterns.md | 7 ++--- scripts/bulk_fix_instruction_joy.py | 31 ++++++++++++++++--- .../tests/test_bulk_fix_instruction_joy.py | 4 +-- scripts/validate_positive_instruction_docs.py | 4 +++ .../references/knowledge-base.md | 4 +-- .../references/response-drafting.md | 2 +- .../references/triage-methodology.md | 2 +- .../design/references/design-critique.md | 2 +- .../finance/references/variance-analysis.md | 2 +- skills/business/hr/references/org-planning.md | 4 +-- .../hr/references/performance-management.md | 2 +- skills/business/hr/references/recruiting.md | 4 +-- .../legal/references/legal-writing.md | 2 +- .../references/llm-legal-failure-modes.md | 2 +- .../marketing/references/content-strategy.md | 6 ++-- .../marketing/references/email-sequences.md | 2 +- .../references/change-management.md | 2 +- .../references/process-documentation.md | 2 +- .../operations/references/risk-assessment.md | 2 +- .../references/runbook-authoring.md | 2 +- .../references/vendor-management.md | 2 +- .../references/metrics-review.md | 4 +-- .../references/spec-writing.md | 2 +- .../references/daily-weekly-planning.md | 2 +- .../productivity/references/status-updates.md | 2 +- .../sales/references/outreach-patterns.md | 2 +- .../references/ruff-rules-reference.md | 2 +- .../references/anti-ai-slide-rules.md | 2 +- .../references/pre-publish-seo-guidelines.md | 8 ++--- .../publish/references/seo-guidelines.md | 2 +- .../html-artifact/references/design-system.md | 2 +- .../references/interaction-patterns.md | 2 +- skills/meta/skill-creator/SKILL.md | 10 +++--- .../references/agent-template.md | 2 +- .../references/preferred-patterns.md | 4 +-- .../references/skill-template.md | 4 +-- .../references/commit-banned-patterns.md | 2 +- .../references/pattern-categories.md | 2 +- .../references/receiving-feedback.md | 13 +++----- 45 files changed, 95 insertions(+), 74 deletions(-) diff --git a/agents/database-engineer/references/sql.md b/agents/database-engineer/references/sql.md index 8ba05810..ed65d715 100644 --- a/agents/database-engineer/references/sql.md +++ b/agents/database-engineer/references/sql.md @@ -232,7 +232,7 @@ user = session.query(User).filter(User.id == user_id).first() --- -### Avoid Functions on Indexed Columns in WHERE +### Use Raw Columns in WHERE Clauses for Index Hits **Detection**: ```bash # Find function calls wrapping column names in WHERE clauses diff --git a/agents/golang-general-engineer/references/go-errors.md b/agents/golang-general-engineer/references/go-errors.md index 83a01057..77d34943 100644 --- a/agents/golang-general-engineer/references/go-errors.md +++ b/agents/golang-general-engineer/references/go-errors.md @@ -381,7 +381,7 @@ if errors.As(err, &validationErr) { - Add context to wrapped errors - Use `errors.Is()` to check for specific errors - Use `errors.As()` to extract error details -- Don't wrap errors you want to hide +- Return errors unwrapped when callers should not match them with errors.Is --- diff --git a/agents/hook-development-engineer/references/preferred-patterns.md b/agents/hook-development-engineer/references/preferred-patterns.md index 8fb37401..954dce75 100644 --- a/agents/hook-development-engineer/references/preferred-patterns.md +++ b/agents/hook-development-engineer/references/preferred-patterns.md @@ -37,7 +37,7 @@ for line in f: # Stops reading after finding the match -- O(1) best case ``` -Avoid loading the entire file into memory and iterating through it. Parse only what is needed, and exit as soon as the relevant data is found. +Parse only what is needed and exit as soon as the relevant data is found. Read files incrementally rather than loading entire contents into memory. **Why this matters**: Hooks fire on every tool call. A hook that takes 200ms adds 200ms to every Read, Edit, Write, and Bash invocation. At 50+ tool calls per session, that is 10+ seconds of pure overhead. diff --git a/agents/performance-optimization-engineer/references/metrics-and-monitoring.md b/agents/performance-optimization-engineer/references/metrics-and-monitoring.md index e845c081..740749ab 100644 --- a/agents/performance-optimization-engineer/references/metrics-and-monitoring.md +++ b/agents/performance-optimization-engineer/references/metrics-and-monitoring.md @@ -63,7 +63,7 @@ onINP(sendToAnalytics, { reportAllChanges: true }) // INP updates on each intera ### Sampling Strategy for High-Traffic Sites -Don't send 100% of metric events — use sampling to reduce costs without losing statistical significance. +Sample metric events (1-10%) to reduce costs while maintaining statistical significance. ```typescript const SAMPLE_RATE = 0.1 // 10% sample diff --git a/agents/python-general-engineer/references/python-errors.md b/agents/python-general-engineer/references/python-errors.md index e069ad37..a76f6a5a 100644 --- a/agents/python-general-engineer/references/python-errors.md +++ b/agents/python-general-engineer/references/python-errors.md @@ -85,7 +85,7 @@ if __name__ == "__main__": **Prevention**: - Only use `asyncio.run()` at the top level of scripts - In notebooks, use `await` directly -- Don't nest `asyncio.run()` calls +- Use a single top-level `asyncio.run()` and await coroutines within it --- diff --git a/agents/testing-automation-engineer/references/preferred-patterns.md b/agents/testing-automation-engineer/references/preferred-patterns.md index d6e58b23..31da8f49 100644 --- a/agents/testing-automation-engineer/references/preferred-patterns.md +++ b/agents/testing-automation-engineer/references/preferred-patterns.md @@ -158,7 +158,7 @@ it('calculates discount', () => { **Why it's wrong:** - Tests give false confidence - they pass even when code broken -- Don't actually verify correct behavior +- Fail to verify correct behavior - Waste CI/CD time without providing value - Can mask regressions and bugs diff --git a/agents/typescript-frontend-engineer/references/typescript-preferred-patterns.md b/agents/typescript-frontend-engineer/references/typescript-preferred-patterns.md index e7e331c6..cd926f69 100644 --- a/agents/typescript-frontend-engineer/references/typescript-preferred-patterns.md +++ b/agents/typescript-frontend-engineer/references/typescript-preferred-patterns.md @@ -61,8 +61,7 @@ interface ApiResponse { ``` **When to use**: -- NEVER use `any` without explicit justification -- If absolutely necessary, add a comment explaining why +- Use specific types; when `any` is unavoidable, add a comment explaining why - Consider `unknown` instead - forces type checking before use --- @@ -299,10 +298,8 @@ const edgeCase = complexTypeFunction(input) ``` **When to use**: -- NEVER use `@ts-ignore` or `@ts-nocheck` without thorough justification -- If used, add detailed comment explaining WHY and what's being ignored +- Replace `@ts-ignore` with `@ts-expect-error` (provides compile-time checking); add a comment when suppression is necessary - Link to GitHub issue if it's a TypeScript bug -- Prefer `@ts-expect-error` over `@ts-ignore` (fails if error is fixed) --- diff --git a/scripts/bulk_fix_instruction_joy.py b/scripts/bulk_fix_instruction_joy.py index 5c636f6d..18c6d15a 100755 --- a/scripts/bulk_fix_instruction_joy.py +++ b/scripts/bulk_fix_instruction_joy.py @@ -23,12 +23,35 @@ "CLAUDE.md", ] SAFE_REWRITES = { - "## Anti-Patterns": "## Patterns to Detect and Fix", - "## Common Anti-Patterns": "## Common Patterns to Detect and Fix", - "## Anti-Pattern Catalog": "## Pattern Catalog", - "## Operational Anti-Patterns": "## Operational Patterns to Detect and Fix", + # Heading-level Anti-Pattern renames (mechanical, domain-independent) + "## Anti-Patterns": "## Common Failure Modes", + "### Anti-Patterns": "### Common Failure Modes", + "## Common Anti-Patterns": "## Common Failure Modes", + "## Anti-Pattern Catalog": "## Failure Mode Catalog", + "## Operational Anti-Patterns": "## Operational Failure Modes", + "## Anti-Patterns in Runbook Authoring": "## Runbook Authoring Failure Modes", + "### Anti-Patterns (never produce these)": "### Failure Modes (detect and fix these)", "### FORBIDDEN Patterns (HARD GATE)": "### Hard Gate Patterns", "### Anti-Pattern Checklist: What NOT To Do": "### Pattern Checklist: What to Detect and Fix", + # Domain-specific Anti-Pattern headings + "## Vendor Management Anti-Patterns": "## Vendor Management Failure Modes", + "## Triage Anti-Patterns": "## Triage Failure Modes", + "## Risk Assessment Anti-Patterns": "## Risk Assessment Failure Modes", + "### Retro Anti-Patterns with Corrections": "### Retro Failure Modes with Corrections", + "### Reorg Anti-Patterns": "### Reorg Failure Modes", + "### Question Design Anti-Patterns": "### Question Design Failure Modes", + "## Process Documentation Anti-Patterns": "## Process Documentation Failure Modes", + "### Planning Anti-Patterns with Corrections": "### Planning Failure Modes with Corrections", + "### Org Design Anti-Patterns": "### Org Design Failure Modes", + "### Onboarding Anti-Patterns": "### Onboarding Failure Modes", + "## KB Quality Anti-Patterns": "## KB Quality Failure Modes", + "### Follow-Up Anti-Patterns": "### Follow-Up Failure Modes", + "#### Feedback Anti-Patterns": "#### Feedback Failure Modes", + "### De-escalation Anti-Patterns": "### De-escalation Failure Modes", + "### Dashboard Anti-Patterns": "### Dashboard Failure Modes", + "## Critique Anti-Patterns to Avoid": "## Critique Failure Modes", + "### Common Funnel Anti-Patterns": "### Common Funnel Failure Modes", + "## Change Management Anti-Patterns": "## Change Management Failure Modes", } PRIMARY_PATTERNS = [ ("NEVER", re.compile(r"\bNEVER\b")), diff --git a/scripts/tests/test_bulk_fix_instruction_joy.py b/scripts/tests/test_bulk_fix_instruction_joy.py index 5a52ef9a..d0feadcb 100755 --- a/scripts/tests/test_bulk_fix_instruction_joy.py +++ b/scripts/tests/test_bulk_fix_instruction_joy.py @@ -17,7 +17,7 @@ def test_scan_file_marks_safe_heading_rewrite(tmp_path: Path) -> None: path.write_text("## Anti-Patterns\n\nBody\n", encoding="utf-8") findings = _mod.scan_file(path) assert len(findings) == 1 - assert findings[0].safe_fix == "## Patterns to Detect and Fix" + assert findings[0].safe_fix == "## Common Failure Modes" def test_apply_safe_rewrites_rewrites_heading_only(tmp_path: Path) -> None: @@ -26,7 +26,7 @@ def test_apply_safe_rewrites_rewrites_heading_only(tmp_path: Path) -> None: changed = _mod.apply_safe_rewrites(path) assert changed == 2 text = path.read_text(encoding="utf-8") - assert "## Patterns to Detect and Fix" in text + assert "## Common Failure Modes" in text assert "### Hard Gate Patterns" in text diff --git a/scripts/validate_positive_instruction_docs.py b/scripts/validate_positive_instruction_docs.py index 3f7f18e0..cee002d6 100755 --- a/scripts/validate_positive_instruction_docs.py +++ b/scripts/validate_positive_instruction_docs.py @@ -40,6 +40,10 @@ # not toolkit operator instructions. Contextual exception per instruction-rubric.md. "voice-andy-nemmity", "voice-vexjoy", + # PHILOSOPHY.md uses negative patterns as quoted examples in a teaching table + # (e.g. "NEVER edit code directly" → "Route all code modifications..."). + # The patterns are the subject, not instructions. + "PHILOSOPHY.md", ) diff --git a/skills/business/customer-support/references/knowledge-base.md b/skills/business/customer-support/references/knowledge-base.md index ae8d652f..ca37b856 100644 --- a/skills/business/customer-support/references/knowledge-base.md +++ b/skills/business/customer-support/references/knowledge-base.md @@ -313,7 +313,7 @@ Billing & Account | FAQ | Detailed article | "For a full walkthrough, see [Guide]" | | Known issue | Workaround | Keep problem-to-solution chain short | -Avoid circular links unless both articles are genuinely useful entry points. Use relative links within the KB -- they survive restructuring. +Link articles in one direction unless both are genuinely useful entry points. Use relative links within the KB — they survive restructuring. --- @@ -397,7 +397,7 @@ Transform the ticket-specific resolution into a general guide: --- -## KB Quality Anti-Patterns +## KB Quality Failure Modes | Anti-Pattern | Problem | Fix | |-------------|---------|-----| diff --git a/skills/business/customer-support/references/response-drafting.md b/skills/business/customer-support/references/response-drafting.md index a8e072d0..479126f0 100644 --- a/skills/business/customer-support/references/response-drafting.md +++ b/skills/business/customer-support/references/response-drafting.md @@ -75,7 +75,7 @@ When a customer is angry, frustrated, or escalating. The goal is not to win an a | "You need to..." | "Here's how to resolve this: [steps]" | Directive language feels adversarial under stress | -### De-escalation Anti-Patterns +### De-escalation Failure Modes | Anti-Pattern | Why It Fails | |-------------|-------------| diff --git a/skills/business/customer-support/references/triage-methodology.md b/skills/business/customer-support/references/triage-methodology.md index 39d94315..da34108c 100644 --- a/skills/business/customer-support/references/triage-methodology.md +++ b/skills/business/customer-support/references/triage-methodology.md @@ -283,7 +283,7 @@ Every triage produces this structured output: --- -## Triage Anti-Patterns +## Triage Failure Modes | Anti-Pattern | Problem | Correct Approach | |-------------|---------|-----------------| diff --git a/skills/business/design/references/design-critique.md b/skills/business/design/references/design-critique.md index 1cc530ed..f658fe73 100644 --- a/skills/business/design/references/design-critique.md +++ b/skills/business/design/references/design-critique.md @@ -194,7 +194,7 @@ Simulate a new user attempting a specific task. For each step: --- -## Critique Anti-Patterns to Avoid +## Critique Failure Modes | Anti-pattern | Do instead | |-------------|-----------| diff --git a/skills/business/finance/references/variance-analysis.md b/skills/business/finance/references/variance-analysis.md index fd14d206..e8902cc4 100644 --- a/skills/business/finance/references/variance-analysis.md +++ b/skills/business/finance/references/variance-analysis.md @@ -157,7 +157,7 @@ Every narrative must be: | Actionable | Identifies required follow-up or decision | | Concise | 2-4 sentences. No filler | -### Anti-Patterns (never produce these) +### Failure Modes (detect and fix these) | Anti-Pattern | Why It Fails | Fix | |-------------|-------------|-----| diff --git a/skills/business/hr/references/org-planning.md b/skills/business/hr/references/org-planning.md index 3dee30b5..d7818452 100644 --- a/skills/business/hr/references/org-planning.md +++ b/skills/business/hr/references/org-planning.md @@ -35,7 +35,7 @@ Headcount modeling, org design principles, capacity planning, and people analyti | Single points of failure | 0 critical | 1-2 | >3 (bus factor risk) | | Skip-level ratio | Every IC has skip-level access | Some don't | No skip-levels happening | -### Org Design Anti-Patterns +### Org Design Failure Modes | Anti-Pattern | Symptom | Root Cause | Fix | |-------------|---------|-----------|-----| @@ -230,7 +230,7 @@ Composite risk score based on multiple factors: | **Team kickoff** | Week 1 | New teams | Mission, priorities, working agreements | | **30-day check-in** | Day 30 | All affected | How's it going, what needs adjustment | -### Reorg Anti-Patterns +### Reorg Failure Modes | Anti-Pattern | Risk | Prevention | |-------------|------|-----------| diff --git a/skills/business/hr/references/performance-management.md b/skills/business/hr/references/performance-management.md index 86c32e9f..e5939cdb 100644 --- a/skills/business/hr/references/performance-management.md +++ b/skills/business/hr/references/performance-management.md @@ -97,7 +97,7 @@ Purpose: Document performance assessment, provide development guidance, justify | Gap identification | "You're strong at execution. The gap I see is in proactive communication — stakeholders are sometimes surprised by delays." | Names the specific gap between current and expected. | | Frequency + evidence | "In the last quarter, 3 of 5 project updates were late by more than a day. Let's discuss what's causing this." | Data-driven. Not "you're always late." | -#### Feedback Anti-Patterns +#### Feedback Failure Modes | Anti-Pattern | Problem | Better | |-------------|---------|--------| diff --git a/skills/business/hr/references/recruiting.md b/skills/business/hr/references/recruiting.md index a706068d..8f8dc1eb 100644 --- a/skills/business/hr/references/recruiting.md +++ b/skills/business/hr/references/recruiting.md @@ -100,7 +100,7 @@ For each role, define 4-6 competencies. Each competency gets dedicated interview | Trained interviewers | Everyone on the panel has completed structured interviewing training. | | Consistent questions | Same question set per competency across all candidates for the same role. | -### Question Design Anti-Patterns +### Question Design Failure Modes | Anti-Pattern | Problem | Better Approach | |-------------|---------|-----------------| @@ -182,7 +182,7 @@ Date: [Date] | Panel: [Names] | **Days 31-60** | Contribute | Delivers independently on scoped work. Participates in reviews. Identifies one improvement. | | **Days 61-90** | Own | Owns a workstream. Contributes to planning. Can onboard the next new hire. | -### Onboarding Anti-Patterns +### Onboarding Failure Modes | Anti-Pattern | Problem | Fix | |-------------|---------|-----| diff --git a/skills/business/legal/references/legal-writing.md b/skills/business/legal/references/legal-writing.md index 63d45563..f3608a90 100644 --- a/skills/business/legal/references/legal-writing.md +++ b/skills/business/legal/references/legal-writing.md @@ -223,7 +223,7 @@ to any other legal holds, those obligations remain in effect. ## Escalation Triggers -Before generating ANY templated legal response, check these triggers. If any fire, do NOT generate a templated response -- recommend escalation instead. +Before generating ANY templated legal response, check these triggers. If any fire, recommend escalation to qualified counsel instead of generating a template. ### Universal Triggers (All Categories) diff --git a/skills/business/legal/references/llm-legal-failure-modes.md b/skills/business/legal/references/llm-legal-failure-modes.md index 6290716b..0d8b36d0 100644 --- a/skills/business/legal/references/llm-legal-failure-modes.md +++ b/skills/business/legal/references/llm-legal-failure-modes.md @@ -31,7 +31,7 @@ Legal analysis has properties that amplify LLM weaknesses: - LLM provides citation with unusual confidence (no hedging language) **Mitigation:** -- NEVER present a case citation, statute number, or regulatory reference as authoritative without instructing the user to verify +- Mark every case citation, statute number, and regulatory reference as "requires verification" and instruct the user to confirm with primary sources - Use hedging: "regulations such as..." or "provisions similar to..." rather than citing specific sections - For well-known, foundational statutes (GDPR, CCPA, HIPAA), cite the act name and general provision (e.g., "GDPR Article 28") but avoid citing specific subsections unless highly confident - When the user needs specific citations, recommend legal research tools (Westlaw, Lexis, regulatory authority websites) diff --git a/skills/business/marketing/references/content-strategy.md b/skills/business/marketing/references/content-strategy.md index 9563c84a..7fdc0527 100644 --- a/skills/business/marketing/references/content-strategy.md +++ b/skills/business/marketing/references/content-strategy.md @@ -282,14 +282,14 @@ The voice stays constant. Tone adjusts to context. #### Inclusive Language Rules - Gender-neutral: they/them for unknown individuals -- Avoid ableist language ("crazy", "blind spot", "lame") +- Use inclusive alternatives for ableist terms ("unexpected" for "crazy", "oversight" for "blind spot", "weak" for "lame") - "Simple" or "straightforward" instead of "easy" (easy varies by person) -- Avoid culturally specific idioms that don't translate +- Use universally understood phrasing over culturally specific idioms #### Competitor and Category Terms - Use your preferred category framing, not the competitor's -- Avoid terms competitors coined (reinforces their positioning) +- Use original terminology over competitor-coined terms (which reinforce their positioning) - Refer to competitors generically unless direct comparison is the point - Define your differentiation language and use it consistently diff --git a/skills/business/marketing/references/email-sequences.md b/skills/business/marketing/references/email-sequences.md index 59d3c89c..ec53c59f 100644 --- a/skills/business/marketing/references/email-sequences.md +++ b/skills/business/marketing/references/email-sequences.md @@ -128,7 +128,7 @@ Map each email to a specific stage: - Under 50 characters (35-40 optimal for mobile) - No ALL CAPS words - No excessive punctuation (!!!, ???) -- Avoid spam triggers: free, act now, limited time, congratulations, click here +- Replace spam-trigger words (free, act now, limited time, congratulations, click here) with specific value statements - Preview text complements -- never repeats -- the subject line - Always provide 2-3 options per email for A/B testing diff --git a/skills/business/operations/references/change-management.md b/skills/business/operations/references/change-management.md index 6bb43822..4f8f20bc 100644 --- a/skills/business/operations/references/change-management.md +++ b/skills/business/operations/references/change-management.md @@ -327,7 +327,7 @@ Rollback procedures must be tested before the change. An untested rollback is a --- -## Change Management Anti-Patterns +## Change Management Failure Modes | Anti-Pattern | Symptom | Fix | |-------------|---------|-----| diff --git a/skills/business/operations/references/process-documentation.md b/skills/business/operations/references/process-documentation.md index 02243dd1..239379d8 100644 --- a/skills/business/operations/references/process-documentation.md +++ b/skills/business/operations/references/process-documentation.md @@ -364,7 +364,7 @@ Annual value: 3hr × 48 weeks × $75/hr loaded cost = $10,800 --- -## Process Documentation Anti-Patterns +## Process Documentation Failure Modes | Anti-Pattern | Symptom | Fix | |-------------|---------|-----| diff --git a/skills/business/operations/references/risk-assessment.md b/skills/business/operations/references/risk-assessment.md index 92355ca9..9dd6ca66 100644 --- a/skills/business/operations/references/risk-assessment.md +++ b/skills/business/operations/references/risk-assessment.md @@ -256,7 +256,7 @@ Maintain evidence that risk management is active, not just documented. --- -## Risk Assessment Anti-Patterns +## Risk Assessment Failure Modes | Anti-Pattern | Symptom | Fix | |-------------|---------|-----| diff --git a/skills/business/operations/references/runbook-authoring.md b/skills/business/operations/references/runbook-authoring.md index 731c9b5b..5a9bed21 100644 --- a/skills/business/operations/references/runbook-authoring.md +++ b/skills/business/operations/references/runbook-authoring.md @@ -349,7 +349,7 @@ Review the runbook when any of these occur: --- -## Anti-Patterns in Runbook Authoring +## Runbook Authoring Failure Modes | Anti-Pattern | Example | Fix | |-------------|---------|-----| diff --git a/skills/business/operations/references/vendor-management.md b/skills/business/operations/references/vendor-management.md index 03409c9e..c5c939f2 100644 --- a/skills/business/operations/references/vendor-management.md +++ b/skills/business/operations/references/vendor-management.md @@ -258,7 +258,7 @@ Every vendor relationship should have an exit plan. Not because you plan to leav --- -## Vendor Management Anti-Patterns +## Vendor Management Failure Modes | Anti-Pattern | Symptom | Fix | |-------------|---------|-----| diff --git a/skills/business/product-management/references/metrics-review.md b/skills/business/product-management/references/metrics-review.md index 4c65c662..5f84b9c1 100644 --- a/skills/business/product-management/references/metrics-review.md +++ b/skills/business/product-management/references/metrics-review.md @@ -177,7 +177,7 @@ KR3: 3 core workflows with >80% task completion rate - **Beware averages**: Mean time-to-activate can be misleading if the distribution is bimodal. Use median or percentiles. - **Attribution**: If you changed multiple things, you cannot attribute funnel changes to one change. Run A/B tests for causal claims. -### Common Funnel Anti-Patterns +### Common Funnel Failure Modes | Anti-Pattern | Problem | Fix | |-------------|---------|-----| @@ -327,7 +327,7 @@ Possible explanations: └────────────────────────────────────────┘ ``` -### Dashboard Anti-Patterns +### Dashboard Failure Modes | Anti-Pattern | Why It Fails | |-------------|-------------| diff --git a/skills/business/product-management/references/spec-writing.md b/skills/business/product-management/references/spec-writing.md index 503f837c..310416ab 100644 --- a/skills/business/product-management/references/spec-writing.md +++ b/skills/business/product-management/references/spec-writing.md @@ -77,7 +77,7 @@ Non-Goals: | **S**mall | Completable in one sprint | | **T**estable | Clear verification path | -### Anti-Patterns +### Common Failure Modes | Pattern | Problem | Fix | |---------|---------|-----| diff --git a/skills/business/productivity/references/daily-weekly-planning.md b/skills/business/productivity/references/daily-weekly-planning.md index d54c1e00..f0603fce 100644 --- a/skills/business/productivity/references/daily-weekly-planning.md +++ b/skills/business/productivity/references/daily-weekly-planning.md @@ -56,7 +56,7 @@ Match task difficulty to energy state. Most knowledge workers have predictable e - If more than 3 hours of meetings, only 2 Top 3 items are realistic. Acknowledge this explicitly. - Buffer time is not optional — unplanned work always appears. Plans without buffers fail by noon. -### Planning Anti-Patterns with Corrections +### Planning Failure Modes with Corrections | Anti-Pattern | What Goes Wrong | Do Instead | |-------------|----------------|------------| diff --git a/skills/business/productivity/references/status-updates.md b/skills/business/productivity/references/status-updates.md index ab94c24d..8e17e15d 100644 --- a/skills/business/productivity/references/status-updates.md +++ b/skills/business/productivity/references/status-updates.md @@ -172,7 +172,7 @@ The simplest effective retro format. - What can we change? (specific action, not aspiration) 5. **Decide** (5 min): Pick 1-2 action items. Each has an owner and a deadline. More than 2 actions from a single retro dilutes focus. -### Retro Anti-Patterns with Corrections +### Retro Failure Modes with Corrections | Anti-Pattern | What Goes Wrong | Do Instead | |-------------|----------------|------------| diff --git a/skills/business/sales/references/outreach-patterns.md b/skills/business/sales/references/outreach-patterns.md index 1eb57f32..ac6c93ba 100644 --- a/skills/business/sales/references/outreach-patterns.md +++ b/skills/business/sales/references/outreach-patterns.md @@ -166,7 +166,7 @@ Total email: under 150 words. 5 sentences is ideal. 7 sentences is the hard max. | Follow-up 3 | Day 14 | Break-up email (creates urgency through scarcity) | | LinkedIn touch | Day 5-10 | Parallel channel. Connection request or engage with their content. | -### Follow-Up Anti-Patterns +### Follow-Up Failure Modes | Bad Follow-Up | Why It Fails | Instead | |--------------|-------------|---------| diff --git a/skills/code-quality/code-linting/references/ruff-rules-reference.md b/skills/code-quality/code-linting/references/ruff-rules-reference.md index 71a6e56b..4eafeb00 100644 --- a/skills/code-quality/code-linting/references/ruff-rules-reference.md +++ b/skills/code-quality/code-linting/references/ruff-rules-reference.md @@ -113,7 +113,7 @@ if not items: --- -### Avoid Mutable Default Arguments (B006) +### Use Immutable Default Arguments (B006) **Detection**: ```bash diff --git a/skills/content/pptx-generator/references/anti-ai-slide-rules.md b/skills/content/pptx-generator/references/anti-ai-slide-rules.md index a13b8c6b..0292173d 100644 --- a/skills/content/pptx-generator/references/anti-ai-slide-rules.md +++ b/skills/content/pptx-generator/references/anti-ai-slide-rules.md @@ -16,7 +16,7 @@ AI-generated slides have a distinctive "template pack" aesthetic that audiences **Why it screams AI**: Every AI slide generator and cheap template pack does this. It's the single most recognizable AI-slide tell. Real designers either skip it entirely or use more sophisticated visual hierarchy. -**Rule**: NEVER add a decorative line, rule, or separator below a title. Use font size, weight, and spacing to create hierarchy instead. +**Rule**: Create visual hierarchy with font size, weight, and spacing. Titles stand alone without decorative lines, rules, or separators beneath them. **Detection**: Any `Shape` of type `LINE` or thin `RECTANGLE` (height < 5pt) positioned within 20pt below a title text box. diff --git a/skills/content/publish/references/pre-publish-seo-guidelines.md b/skills/content/publish/references/pre-publish-seo-guidelines.md index ac9edb1e..8d5a843d 100644 --- a/skills/content/publish/references/pre-publish-seo-guidelines.md +++ b/skills/content/publish/references/pre-publish-seo-guidelines.md @@ -34,7 +34,7 @@ - Include primary keyword naturally - Add a call to action when appropriate - Make it unique per page -- Don't just repeat the title +- Write a unique description distinct from the title **Examples:** - Good: "Learn how to diagnose and fix common Kubernetes networking issues including DNS failures, service discovery problems, and network policies. Practical debugging steps included." (169 chars - slightly over but okay) @@ -55,7 +55,7 @@ - Use hyphens, not underscores - Remove stop words (a, the, and, etc.) - Keep it readable and memorable -- Don't change after publication (breaks links) +- Keep stable after publication (changes break links) **YourBlog Convention:** - Format: `YYYY-MM-descriptive-slug.md` @@ -92,7 +92,7 @@ - One H1 only (title) - Use H2 for major sections - Use H3 for subsections within H2 -- Don't skip levels (H2 -> H4) +- Use sequential heading levels (H2 → H3 → H4) - Include keywords in headers naturally - Make headers scannable @@ -126,7 +126,7 @@ Wrap up... - Describe the image content - Include keywords naturally - Keep under 125 characters -- Don't start with "Image of..." +- Describe the content directly ("Dashboard showing monthly revenue" over "Image of a dashboard") **File Names:** - Use descriptive names: `kubernetes-network-diagram.png` diff --git a/skills/content/publish/references/seo-guidelines.md b/skills/content/publish/references/seo-guidelines.md index 8b5f3fa4..9029c63d 100644 --- a/skills/content/publish/references/seo-guidelines.md +++ b/skills/content/publish/references/seo-guidelines.md @@ -77,7 +77,7 @@ Keyword Density = (Number of keyword occurrences / Total word count) * 100 ### Keyword in Headers - Primary keyword should appear in 1-2 H2s naturally -- Don't force keywords into every header +- Place keywords in headers where they fit naturally - Variations are fine: "Debugging Hugo" vs "Hugo Debugging" --- diff --git a/skills/meta/html-artifact/references/design-system.md b/skills/meta/html-artifact/references/design-system.md index 7a50b164..f9fd62ed 100644 --- a/skills/meta/html-artifact/references/design-system.md +++ b/skills/meta/html-artifact/references/design-system.md @@ -115,7 +115,7 @@ Use `min-width` media queries (mobile-first). Container max-width: 1200px. --- -## Anti-Patterns +## Common Failure Modes | Pattern | Do Instead | |---|---| diff --git a/skills/meta/html-artifact/references/interaction-patterns.md b/skills/meta/html-artifact/references/interaction-patterns.md index e72e4e60..c1c24322 100644 --- a/skills/meta/html-artifact/references/interaction-patterns.md +++ b/skills/meta/html-artifact/references/interaction-patterns.md @@ -49,7 +49,7 @@ Request via `--components` flag. Multiple: `--components tabs,collapsible,copy-b ### Keyboard Navigation - Arrow keys navigate sequential content (slides, cards, items) - Track current index, wrap around at boundaries -- Don't intercept when user is typing in input/textarea +- Allow keyboard shortcuts to pass through when focus is in input/textarea - Update counter display (`1/N`) on navigation ### Theme Toggle diff --git a/skills/meta/skill-creator/SKILL.md b/skills/meta/skill-creator/SKILL.md index 55110162..0060f013 100644 --- a/skills/meta/skill-creator/SKILL.md +++ b/skills/meta/skill-creator/SKILL.md @@ -93,7 +93,7 @@ sub-concern of the existing skill. Sub-concerns MUST be added as reference files on the existing skill, not created as separate skills. Pattern (correct): `skills/perses/references/plugins.md` -Anti-pattern (wrong): `skills/perses-plugin-creator/SKILL.md` +Incorrect (creates domain overlap): `skills/perses-plugin-creator/SKILL.md` **Step 3**: If no domain skill exists and the domain has multiple sub-concerns, create the skill with a `references/` directory from the start. @@ -198,11 +198,11 @@ The description is the primary triggering mechanism. Claude tends to undertrigge Constraints belong inline within the workflow step where they apply. Explain the reasoning behind constraints -- "Run with `-race` because race conditions are silent until production" generalizes; "ALWAYS run with -race" does not. -**Do-pair validation** -- After writing any anti-pattern blocks, run: +**Do-pair validation** -- After writing any failure-mode blocks, run: ```bash python3 scripts/validate-references.py --check-do-framing ``` -Every anti-pattern block must have a paired "Do instead" counterpart. Blocks +Every failure-mode block must have a paired "Do instead" counterpart. Blocks without one fail the check. If a prohibition genuinely has no correct alternative, annotate it with `` to pass validation without a "Do instead" block. Ship the skill only after this check exits 0. @@ -369,7 +369,7 @@ staging to confirm exactly one new entry was added. Before declaring the skill shippable, run both checks. They catch different failure modes: joy-check catches grievance-mode framing that drags the model -toward pessimism; do-pair validation catches anti-patterns with no paired +toward pessimism; do-pair validation catches failure modes with no paired "Do instead" counterpart. **Joy-check** (framing). Invoke the `joy-check` skill on the SKILL.md and each @@ -380,7 +380,7 @@ python3 scripts/validate-references.py --check-do-framing ``` This script enforces the positive-pairing rule that joy-check encodes -structurally: every anti-pattern gets a constructive counterpart. Use it when +structurally: every failure mode gets a constructive counterpart. Use it when dispatching the full `joy-check` skill is disproportionate (small edits, CI contexts, or when only structural pairing matters). For any new skill that ships prose-heavy references, prefer the full `joy-check` skill -- tone drift diff --git a/skills/meta/skill-creator/references/agent-template.md b/skills/meta/skill-creator/references/agent-template.md index d3a661c9..2fcef292 100644 --- a/skills/meta/skill-creator/references/agent-template.md +++ b/skills/meta/skill-creator/references/agent-template.md @@ -145,7 +145,7 @@ This agent operates as an operator for [domain/function], configuring Claude's b ### Hardcoded Behaviors (Always Apply) - **CLAUDE.md Compliance**: Read and follow repository CLAUDE.md files before any implementation. Project instructions override default agent behaviors. -- **Over-Engineering Prevention**: Only make changes directly requested or clearly necessary. Keep solutions simple and focused. Don't add features, refactor code, or make "improvements" beyond what was asked. Reuse existing abstractions over creating new ones. Three-line repetition is better than premature abstraction. +- **Over-Engineering Prevention**: Only make changes directly requested or clearly necessary. Keep solutions simple and focused. Scope changes to what was directly requested. Reuse existing abstractions over creating new ones. Three-line repetition is better than premature abstraction. - **[Domain-Specific Non-Negotiable 1]**: [Description] - **[Domain-Specific Non-Negotiable 2]**: [Description] - **[Domain-Specific Non-Negotiable 3]**: [Description] diff --git a/skills/meta/skill-creator/references/preferred-patterns.md b/skills/meta/skill-creator/references/preferred-patterns.md index af786640..864b6228 100644 --- a/skills/meta/skill-creator/references/preferred-patterns.md +++ b/skills/meta/skill-creator/references/preferred-patterns.md @@ -280,7 +280,7 @@ find skills/ -name 'SKILL.md' -exec dirname {} \; | xargs -I{} basename {} | gre ## Pair Mandates With Rationale -Attach a "because X" reason to every instruction. Bare imperatives (ALWAYS, NEVER, MUST) cannot generalize to edge cases the author did not anticipate. Reasoned constraints let the model make the right call in ambiguous situations. +Attach a "because X" reason to every instruction. Bare imperatives without reasoning cannot generalize to edge cases the author did not anticipate. Reasoned constraints let the model make the right call in ambiguous situations. ```markdown ## Instructions @@ -303,7 +303,7 @@ grep -n 'ALWAYS\|NEVER\|MUST' skills/*/SKILL.md | grep -v 'because\|since\|so th ## Add Negative Triggers for Exclusions -When a skill has a broad domain that overlaps with specialized skills, add explicit "Do NOT use for" clauses. This prevents overtriggering on requests that belong to a more specialized skill. +When a skill has a broad domain that overlaps with specialized skills, add explicit exclusion clauses (e.g. "Use X skill instead for Y"). This prevents overtriggering on requests that belong to a more specialized skill. ```yaml description: | diff --git a/skills/meta/skill-creator/references/skill-template.md b/skills/meta/skill-creator/references/skill-template.md index a06d78c1..2d68a986 100644 --- a/skills/meta/skill-creator/references/skill-template.md +++ b/skills/meta/skill-creator/references/skill-template.md @@ -283,11 +283,11 @@ Constraint: [Domain-specific rule that applies HERE] LLMs follow instructions better when they understand the reasoning behind them. For every constraint or rule in a skill, prefer explaining **why** it matters alongside the directive. -**Yellow flag**: If you find yourself writing `ALWAYS` or `NEVER` in all caps without explanation, reframe it. Add the reasoning so the model understands the importance and can generalize correctly to edge cases. +**Yellow flag**: Pair every capitalized imperative (ALWAYS, MUST) with reasoning. The model generalizes better to edge cases when it understands the "because" behind a rule. | Pattern | Less Effective | More Effective | |---------|---------------|----------------| -| Constraint | `NEVER use console.log in production code` | `Avoid console.log in production — it blocks the event loop on high-throughput paths and leaks internal state to browser devtools` | +| Constraint | `Remove console.log before shipping` | `Remove console.log before shipping — it blocks the event loop on high-throughput paths and leaks internal state to browser devtools` | | Requirement | `ALWAYS validate inputs before processing` | `Validate inputs before processing because malformed data at this boundary propagates silently through 3 downstream services` | | Gate | `MUST pass lint before committing` | `Pass lint before committing — the CI will reject it anyway, and fixing lint after commit creates noisy fix-lint commits in the PR` | diff --git a/skills/process/pr-workflow/references/commit-banned-patterns.md b/skills/process/pr-workflow/references/commit-banned-patterns.md index c5c6abaf..9fa77fed 100644 --- a/skills/process/pr-workflow/references/commit-banned-patterns.md +++ b/skills/process/pr-workflow/references/commit-banned-patterns.md @@ -299,7 +299,7 @@ git commit --no-verify -m "message" - Repository doesn't use pr-workflow commit intent - Testing/experimentation (non-production) -**NEVER bypass for**: +**Enforce strictly for**: - Production commits - Public repositories - Team collaboration diff --git a/skills/process/pr-workflow/references/pattern-categories.md b/skills/process/pr-workflow/references/pattern-categories.md index e848de22..b45531ca 100644 --- a/skills/process/pr-workflow/references/pattern-categories.md +++ b/skills/process/pr-workflow/references/pattern-categories.md @@ -12,7 +12,7 @@ Patterns related to error creation, checking, wrapping, and propagation. - Use `errors.As()` for error type checking - Wrap errors with context using `fmt.Errorf("context: %w", err)` - Check errors immediately after function calls -- Don't ignore errors (no `_ = func()` without comment) +- Handle every error explicitly (annotate `_ = func()` with a comment explaining why) **Example Pattern**: ```markdown diff --git a/skills/review/systematic-code-review/references/receiving-feedback.md b/skills/review/systematic-code-review/references/receiving-feedback.md index 001528bc..c6901583 100644 --- a/skills/review/systematic-code-review/references/receiving-feedback.md +++ b/skills/review/systematic-code-review/references/receiving-feedback.md @@ -17,16 +17,13 @@ WHEN receiving code review feedback: ## No Performative Agreement -**NEVER:** -- "You're absolutely right!" -- "Great point!" / "Excellent feedback!" -- "Thanks for catching that!" - -**INSTEAD:** +**Replace performative responses with action:** - Restate the technical requirement - Ask clarifying questions -- Push back with technical reasoning if wrong -- Just start working (actions > words) +- Push back with technical reasoning when feedback is incorrect +- Start working immediately (actions > words) + +**Skip these filler phrases:** "You're absolutely right!", "Great point!", "Excellent feedback!", "Thanks for catching that!" **When feedback IS correct:** ```