wicked-garden 12.27.0

package/skills/wickedizer/refs/complexity.md

@@ -0,0 +1,278 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Complexity: Keep It Simple
+
+Writing complexity is cognitive load on the reader. Every unnecessary word, section, or concept is debt they pay to understand you.
+
+## Two Types of Complexity
+
+### Essential Complexity
+
+Complexity that exists in the subject matter itself. Can't be removed without losing meaning.
+
+- Technical concepts that require precision
+- Nuanced decisions with real tradeoffs
+- Regulatory or legal requirements
+- Domain-specific terminology
+
+**Don't fight essential complexity.** Explain it clearly, but don't pretend it's simple.
+
+### Accidental Complexity
+
+Complexity introduced by the writer, not required by the subject.
+
+- Jargon when plain language works
+- Hedging when you're actually certain
+- Sections that repeat other sections
+- Structure that doesn't match content
+
+**Accidental complexity is your target.** Remove it ruthlessly.
+
+---
+
+## KISS: Keep It Stupidly Simple
+
+The simplest explanation that's still accurate is usually best.
+
+### Detection Questions
+
+- Could a smart person outside your team understand this?
+- Are you explaining the concept or showing off knowledge?
+- Would removing this sentence change the meaning?
+
+### Application
+
+```
+// BAD: Unnecessarily complex
+The implementation leverages a distributed event-driven
+architecture paradigm to facilitate loosely-coupled
+inter-service communication patterns.
+
+// GOOD: Same meaning, less load
+Services communicate through events, so they don't
+depend on each other directly.
+```
+
+```
+// BAD: Over-explained
+It's important to note that users will need to
+authenticate before accessing the dashboard. This
+authentication step ensures that only authorized
+users can view sensitive data. Without authentication,
+unauthorized access could occur.
+
+// GOOD: Trust the reader
+Users must authenticate before accessing the dashboard.
+```
+
+---
+
+## YAGNI: You Aren't Gonna Need It
+
+Don't write content for hypothetical readers or future scenarios.
+
+### Symptoms of YAGNI Violations
+
+- "For completeness, we should mention..."
+- "Some readers might want to know..."
+- "In case anyone asks about..."
+- Appendices no one requested
+
+### Application
+
+```
+// BAD: Anticipating questions no one asked
+## Authentication Methods
+We use JWT tokens. For historical context, we
+previously used session cookies from 2018-2022,
+which had several limitations including...
+
+[3 paragraphs of history]
+
+## Migration Path from Sessions
+If any services still use sessions...
+
+[Section for a situation that doesn't exist]
+
+// GOOD: What's needed now
+## Authentication
+We use JWT tokens. See [auth docs] for implementation.
+```
+
+**Rule:** Write for the actual audience with actual questions. Add content when someone asks, not before.
+
+---
+
+## DRY: Don't Repeat Yourself
+
+Say it once, say it well, reference it thereafter.
+
+### The Rule of Three
+
+Don't extract or consolidate until you've seen the same content three times. Premature consolidation creates worse problems than repetition.
+
+```
+// Repetition 1: Leave it
+// Repetition 2: Note it, leave it
+// Repetition 3: Now consolidate
+```
+
+### Good Repetition vs. Bad Repetition
+
+**Good (structural repetition):**
+- Consistent headings across similar docs
+- Same format for all work items
+- Repeated structure readers expect
+
+**Bad (content duplication):**
+- Same paragraph in multiple places
+- Restating what a linked doc already says
+- "As mentioned above" (just don't mention it twice)
+
+### Consolidation Patterns
+
+```
+// BAD: Duplicate content
+## Overview
+The system handles 10k requests per second...
+
+## Performance
+The system handles 10k requests per second...
+
+// GOOD: Single source
+## Overview
+The system handles 10k requests per second.
+See Performance for details.
+
+// ALSO GOOD: Just don't repeat
+## Performance
+The system handles 10k requests per second...
+
+[Remove from Overview entirely]
+```
+
+---
+
+## Separation of Concerns
+
+Different purposes should be different sections or documents.
+
+### Single Responsibility for Sections
+
+Each section should have one job:
+- Explain a concept, OR
+- Provide instructions, OR
+- Present evidence, OR
+- Document a decision
+
+```
+// BAD: Mixed concerns
+## API Authentication
+Authentication uses JWT tokens (Bearer scheme).
+To authenticate, include the header "Authorization:
+Bearer <token>". We chose JWT over sessions because
+of scalability requirements documented in ADR-042.
+Tokens expire after 1 hour. To refresh, call POST
+/auth/refresh. The security team reviewed this in Q2.
+
+// GOOD: Separated concerns
+## API Authentication
+Authenticate using JWT Bearer tokens in the
+Authorization header. Tokens expire after 1 hour.
+
+See:
+- [How to authenticate](/docs/auth-howto) - step by step
+- [ADR-042](/decisions/adr-042) - why we chose JWT
+```
+
+---
+
+## Cognitive Load Management
+
+### Limit Concepts per Section
+
+**7±2 Rule:** Readers hold about 5-9 items in working memory.
+
+- Max 7 bullets in a list
+- Max 5-7 concepts before a break
+- Max 3 levels of nesting
+
+### Front-Load Familiar Concepts
+
+Start with what readers know, bridge to what's new.
+
+```
+// BAD: New concept without anchor
+The flurble processor handles all greebling operations
+using a distributed mesh topology.
+
+// GOOD: Anchor to known concept
+Like a load balancer distributes traffic, the flurble
+processor distributes greebling operations across nodes.
+```
+
+### Use Progressive Disclosure
+
+Don't explain everything upfront. Provide depth when readers need it.
+
+```
+Layer 1: What it does (everyone reads)
+Layer 2: How to use it (most readers)
+Layer 3: How it works (some readers)
+Layer 4: Implementation details (few readers)
+```
+
+---
+
+## Simplification Techniques
+
+### Remove Weasel Words
+
+| Weasel | Problem | Fix |
+|--------|---------|-----|
+| "Basically" | Implies complexity you're hiding | Just explain simply |
+| "Simply" | Often precedes something not simple | Remove and check |
+| "Obviously" | If obvious, why say it? | Remove |
+| "Clearly" | Same | Remove |
+| "In order to" | Wordy | "To" |
+| "Utilize" | Fancy "use" | "Use" |
+
+### Remove Meta-Commentary
+
+```
+// BAD: Talking about what you're about to say
+In this section, we will discuss the authentication
+approach. First, we'll cover the basics, then we'll
+dive into implementation details.
+
+// GOOD: Just say it
+Authentication uses JWT tokens...
+```
+
+### Remove Obvious Transitions
+
+```
+// BAD: Over-connected
+First, we need to authenticate. Next, we fetch the
+data. Then, we process it. Finally, we return results.
+
+// GOOD: Let structure carry order
+1. Authenticate
+2. Fetch data
+3. Process
+4. Return results
+```
+
+---
+
+## Quick Reference
+
+| Principle | Question to Ask |
+|-----------|-----------------|
+| KISS | Can I say this simpler without losing meaning? |
+| YAGNI | Does anyone actually need this? |
+| DRY | Have I said this elsewhere? |
+| Separation | Is this section doing one job? |
+| Cognitive load | How many new concepts at once? |

package/skills/wickedizer/refs/de-ai-pass.md

@@ -0,0 +1,140 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# De-AI Pass: Removing AI-Generated Tells
+
+This reference covers identifying and removing patterns that signal AI-generated content. The goal isn't to hide AI involvement - it's to remove artifacts that damage trust and clarity.
+
+## Why This Matters
+
+AI-generated content often fails not because it's wrong, but because it's recognizably synthetic. Readers develop "AI fatigue" and dismiss content that triggers pattern recognition.
+
+**The fix isn't deception - it's quality.** Human writers produce these same patterns when writing lazily. We're removing bad writing habits, not fingerprints.
+
+## The Five Categories of AI Tells
+
+### 1. Chatbot Artifacts
+
+Direct signals that text came from a conversation with an AI.
+
+| Pattern | Example | Fix |
+|---------|---------|-----|
+| Sign-off phrases | "Hope this helps!" | Delete |
+| Prompt acknowledgment | "Great question!" | Delete |
+| Availability offers | "Let me know if you need more" | Delete |
+| Validation filler | "That's a great approach" | Delete |
+| Meta-commentary | "I'll break this down into sections" | Just do it |
+
+**Rule:** If you wouldn't write it in a formal document, delete it.
+
+### 2. Promotional Language
+
+Excessive positivity and significance inflation.
+
+| Pattern | Example | Fix |
+|---------|---------|-----|
+| Unearned superlatives | "groundbreaking", "revolutionary" | Remove or prove |
+| Significance inflation | "pivotal moment", "game-changer" | State impact specifically |
+| Future hype | "unprecedented opportunities" | Name the opportunities |
+| Vague benefits | "driving value across the organization" | What value? For whom? |
+
+**Rule:** If a claim can't be measured or verified, downgrade or delete it.
+
+### 3. Hedge Stacking
+
+Multiple qualifiers that destroy confidence.
+
+**Before:**
+> This approach could potentially possibly help to somewhat improve performance in certain scenarios.
+
+**After:**
+> This approach improves read performance for queries under 100ms.
+
+| Hedge Stack | Problem | Better |
+|-------------|---------|--------|
+| "could potentially" | Double hedge | "can" or remove |
+| "might be able to" | Triple hedge | "can" or state conditions |
+| "in some cases, sometimes" | Redundant | Pick one, be specific |
+| "it is believed that" | Passive + hedge | State source or remove |
+
+**Rule:** One hedge per claim maximum. If you're that uncertain, cut the claim.
+
+### 4. Structural Tells
+
+Patterns in how content is organized.
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| Rule of three | Everything in threes feels forced | Use 2 or 4 when that's the real count |
+| Parallel construction | "Not just X, but Y. Not just Y, but Z" | Vary structure |
+| Transitional spam | "Additionally... Furthermore... Moreover..." | Just continue |
+| Cadence uniformity | Every sentence same length/shape | Vary rhythm |
+
+**Rule:** Humans are messy. Perfect symmetry signals automation.
+
+### 5. Vague Attribution
+
+Citations to unnamed authorities.
+
+| Pattern | Example | Fix |
+|---------|---------|-----|
+| Unnamed experts | "experts agree" | Name them or delete |
+| Passive voice attribution | "it is widely accepted" | By whom? |
+| Implied research | "studies show" | Cite or delete |
+| Industry consensus | "industry leaders believe" | Name one |
+
+**Rule:** Cite specifically or don't cite at all.
+
+## The De-AI Process
+
+### Pass 1: Delete Obvious Artifacts
+
+Quick scan for chatbot phrases, sign-offs, meta-commentary. Delete on sight.
+
+### Pass 2: Audit Claims
+
+For each claim, ask:
+- Can this be verified from the source input?
+- Is it supported by evidence?
+- Is it overstated?
+
+Options: keep, downgrade to opinion, delete.
+
+### Pass 3: Vary Structure
+
+- Break up uniform sentence lengths
+- Reduce transitions to only necessary ones
+- Let section flow naturally
+
+### Pass 4: Specificity Check
+
+Replace each vague phrase with a specific alternative or delete:
+
+| Vague | Ask | Specific |
+|-------|-----|----------|
+| "improve efficiency" | By how much? How measured? | "reduce processing time from 4s to 1.2s" |
+| "enhance collaboration" | What action? What outcome? | "teams can now edit the same doc" |
+| "streamline workflows" | Which workflows? What changes? | "approval requires 2 steps instead of 5" |
+
+## When to Keep Hedges
+
+Hedging isn't always wrong. Keep hedges when:
+
+- **Genuine uncertainty exists** - "Performance may vary based on load"
+- **Stating limitations** - "This approach works best for read-heavy workloads"
+- **Legal/compliance requires it** - "Results not guaranteed"
+- **Preliminary data** - "Initial tests suggest..."
+
+The problem isn't hedging - it's hedging when you're not actually uncertain.
+
+## Credibility Over Casualness
+
+"Human" doesn't mean informal. It means:
+
+- Claims match evidence
+- Structure serves content
+- Voice is consistent
+- Reader trusts the text
+
+A formal document can be human. A casual message can be AI-ish. The distinction is credibility, not tone.

package/skills/wickedizer/refs/failure-modes.md

@@ -0,0 +1,249 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Failure Modes: What to Watch For
+
+This reference catalogs common failure modes in rewritten content. Use it as a checklist or debugging guide when output doesn't feel right.
+
+## Language & Tone Failures
+
+### Transition Word Spam
+
+**Symptoms:**
+- "Additionally", "Furthermore", "Moreover" appear multiple times
+- Every paragraph starts with a connector
+- Text feels like a list pretending to be prose
+
+**Fix:** Delete most transitions. Good structure doesn't need signposting.
+
+**Before:**
+> Additionally, the system supports caching. Furthermore, it includes retry logic. Moreover, there's built-in monitoring.
+
+**After:**
+> The system supports caching, retry logic, and built-in monitoring.
+
+---
+
+### Significance Inflation
+
+**Symptoms:**
+- "Testament to", "pivotal", "transformative", "game-changing"
+- Everything sounds like a press release
+- Claims don't match evidence
+
+**Fix:** Delete the inflation. State what happened, let reader judge significance.
+
+**Before:**
+> This pivotal achievement represents a transformative milestone that serves as a testament to the team's dedication.
+
+**After:**
+> The team shipped the feature on schedule.
+
+---
+
+### Rhetorical Scaffolding
+
+**Symptoms:**
+- "Not just X, but Y"
+- "While X is important, Y is even more critical"
+- Contrast patterns that add words but not meaning
+
+**Fix:** State the point directly.
+
+**Before:**
+> This isn't just about improving performance. It's about fundamentally reimagining how we approach the problem.
+
+**After:**
+> This improves performance by rethinking our cache strategy.
+
+---
+
+### Synonym Cycling
+
+**Symptoms:**
+- Same concept called different names in same document
+- "Users", "customers", "clients", "stakeholders" used interchangeably
+- Reader unsure if terms mean different things
+
+**Fix:** Pick one term, use it consistently. Repetition is fine.
+
+---
+
+### Cadence Uniformity
+
+**Symptoms:**
+- Every sentence is the same length
+- Same subject-verb-object structure repeats
+- Text feels robotic despite correct grammar
+
+**Fix:** Vary sentence length. Mix simple and compound. Short sentence. Then a longer one that develops the idea further.
+
+---
+
+## Content & Credibility Failures
+
+### Fake Specificity
+
+**Symptoms:**
+- "Studies show" without citation
+- Invented metrics ("reduces costs by 40%")
+- Named experts who don't exist
+- Quotes that seem too perfect
+
+**Fix:** Delete unsupported claims. If the input doesn't have the data, the output can't either.
+
+---
+
+### Vague Attribution
+
+**Symptoms:**
+- "Experts agree"
+- "Industry leaders believe"
+- "It is widely accepted"
+- "Research indicates"
+
+**Fix:** Name the source or remove the attribution. "Research indicates" without citation is worse than no citation.
+
+---
+
+### Scope Fog
+
+**Symptoms:**
+- No owners named
+- No dates or deadlines
+- No explicit scope boundaries
+- No success criteria
+
+**Fix:** If input has this info, surface it. If input lacks it, note the gap or remove claims that depend on it.
+
+---
+
+### Empty Conclusions
+
+**Symptoms:**
+- "The future looks bright"
+- "We're excited about what's ahead"
+- "This is just the beginning"
+- Generic optimism that applies to anything
+
+**Fix:** End with substance: decision needed, next step, open question, or measurable outcome.
+
+---
+
+## Structure Failures
+
+### Headers That Restate Bullets
+
+**Symptoms:**
+- Header: "Benefits"
+- Bullet 1: "Benefit: Faster performance"
+- The word "benefit" appears three times
+
+**Fix:** Let bullets speak for themselves or make headers more specific.
+
+---
+
+### Bullets Without Verbs
+
+**Symptoms:**
+- Bullets that are just noun phrases
+- "Improved efficiency"
+- "Enhanced collaboration"
+- "Streamlined processes"
+
+**Fix:** Add verbs or delete the bullet. "Improved efficiency" becomes "Processing time dropped from 4s to 1s."
+
+---
+
+### Excessive Nesting
+
+**Symptoms:**
+- Sub-bullets under sub-bullets
+- More than 2 levels of indentation
+- Lists inside lists inside lists
+
+**Fix:** Flatten. If content needs that much structure, it's probably multiple sections.
+
+---
+
+### Rule of Three Addiction
+
+**Symptoms:**
+- Everything comes in threes
+- Two items become three with filler
+- Four items squeezed to three
+
+**Fix:** Use the real count. Two is fine. Four is fine. Forced three is obvious.
+
+---
+
+### Decorative Elements
+
+**Symptoms:**
+- Emojis in professional docs
+- Unnecessary horizontal rules
+- Forced symmetry between sections
+- Headers for single-paragraph sections
+
+**Fix:** Remove decoration. Let content carry itself.
+
+---
+
+## Process Failures
+
+### Meaning Drift
+
+**Symptoms:**
+- Constraints from input are softened
+- Decisions become suggestions
+- Scope expands or contracts unintentionally
+
+**Fix:** Compare input and output side by side. Immutables must survive.
+
+---
+
+### Over-Compression
+
+**Symptoms:**
+- Important details lost
+- Context removed that reader needs
+- Output is shorter but less useful
+
+**Fix:** Compression should remove fluff, not substance. Re-read input for what matters.
+
+---
+
+### Under-Compression
+
+**Symptoms:**
+- Output is same length or longer
+- Added words without added meaning
+- "Improvements" that are actually additions
+
+**Fix:** Every added word needs justification. Default is shorter.
+
+---
+
+### Format Mismatch
+
+**Symptoms:**
+- Exec summary that's a full doc
+- Work item that's a paragraph
+- Code comment that's a tutorial
+
+**Fix:** Re-classify the artifact and apply appropriate constraints.
+
+---
+
+## Quick Self-Check
+
+Before finalizing output, ask:
+
+1. **Did I add any facts?** (Should be: No)
+2. **Did I change any decisions or constraints?** (Should be: No)
+3. **Can the reader answer: What? Why? Who owns it? What's next?**
+4. **Would I trust this text if I received it?**
+5. **Is the structure appropriate for the medium?**
+
+If any answer is wrong, go back.