wicked-garden 12.27.0

package/skills/wickedizer/refs/patterns.md

@@ -0,0 +1,282 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Patterns: Reusable Writing Structures
+
+Patterns are proven structures for common writing situations. Don't reinvent—adapt.
+
+## Opening Patterns
+
+### The Direct Lead
+
+State your point in the first sentence.
+
+```
+[What this is] + [Why it matters]
+
+// Example
+JWT authentication replaces sessions across all APIs,
+reducing latency by 40%.
+```
+
+**Use for:** Technical docs, work items, status updates—anything where readers want the point fast.
+
+### The Context-Point Lead
+
+Brief context, then the point.
+
+```
+[One sentence of context]. [Point].
+
+// Example
+After three months of evaluation, we recommend Postgres
+over MongoDB for the new order service.
+```
+
+**Use for:** Decisions, recommendations, proposals where minimal context helps.
+
+### The Problem Lead
+
+Open with the pain, then the solution.
+
+```
+[Problem]. [Solution].
+
+// Example
+Deploy failures increased 40% last quarter. This RFC
+proposes automated rollback triggers.
+```
+
+**Use for:** Proposals, RFCs, business cases—when you need buy-in.
+
+---
+
+## Argument Patterns
+
+### What-So What-Now What
+
+```
+WHAT: [State the fact or situation]
+SO WHAT: [Explain why it matters]
+NOW WHAT: [State the action or decision]
+
+// Example
+WHAT: Customer churn increased from 5% to 8% this quarter.
+SO WHAT: At this rate, we lose $2M ARR by year end.
+NOW WHAT: Propose immediate investment in retention features.
+```
+
+### Problem-Cause-Solution
+
+```
+PROBLEM: [What's broken]
+CAUSE: [Why it's broken]
+SOLUTION: [How to fix it]
+
+// Example
+PROBLEM: API response times exceed SLA (>500ms).
+CAUSE: N+1 queries in the order aggregation endpoint.
+SOLUTION: Implement batch loading, projected 80% improvement.
+```
+
+### Option-Criteria-Recommendation
+
+```
+OPTIONS: [2-3 viable approaches]
+CRITERIA: [How we evaluate]
+RECOMMENDATION: [Which option and why]
+
+// Example
+OPTIONS:
+- A: Build in-house (4 months, full control)
+- B: Buy vendor X ($50k/yr, 2-week setup)
+- C: Open source Y (free, 1 month integration)
+
+CRITERIA: Time to market, long-term cost, flexibility
+
+RECOMMENDATION: Option B. We ship in 2 weeks, cost is
+acceptable, and we can migrate later if needed.
+```
+
+---
+
+## Section Patterns
+
+### The Setup-Payoff
+
+Establish context, then deliver the insight.
+
+```
+SETUP: [Background the reader needs]
+PAYOFF: [The insight or conclusion]
+
+// Example
+SETUP: The cache layer was designed for 1K rps.
+We now serve 10K rps at peak.
+PAYOFF: Cache misses cause 60% of our latency spikes.
+```
+
+### The Comparison
+
+Side-by-side evaluation.
+
+```
+| Aspect | Option A | Option B |
+|--------|----------|----------|
+| Cost | $X | $Y |
+| Time | X weeks | Y weeks |
+| Risk | Low | Medium |
+
+VERDICT: [Which wins and why]
+```
+
+### The Sequence
+
+Ordered steps or timeline.
+
+```
+1. [First step] — [brief note if needed]
+2. [Second step]
+3. [Third step]
+...
+
+// Example
+1. Merge feature branch — requires 2 approvals
+2. Deploy to staging — automated
+3. QA validation — 24 hour window
+4. Production deploy — requires release train
+```
+
+---
+
+## Whole-Document Patterns
+
+### The One-Pager
+
+For decisions that need quick alignment.
+
+```
+## [Decision Title]
+
+**TL;DR:** [One sentence summary]
+
+**Context:** [2-3 sentences of background]
+
+**Proposal:** [What we should do]
+
+**Alternatives Considered:**
+- [Alt 1]: [Why not]
+- [Alt 2]: [Why not]
+
+**Risks:** [What could go wrong]
+
+**Ask:** [What you need - approval/feedback/resources]
+```
+
+### The Technical RFC
+
+For engineering decisions that need review.
+
+```
+## [RFC Title]
+
+**Status:** Draft | Review | Approved | Superseded
+
+**Author(s):** [Names]
+
+**Reviewers:** [Names]
+
+### Context
+[Why are we here? What problem?]
+
+### Decision
+[What we're doing, unambiguously]
+
+### Alternatives Considered
+[2-3 options with tradeoffs]
+
+### Consequences
+[What changes as a result]
+
+### Migration/Rollout
+[How we get from here to there]
+```
+
+### The Incident Report
+
+For post-mortems and incident documentation.
+
+```
+## [Incident Title] — [Date]
+
+**Severity:** P1/P2/P3
+**Duration:** [Start] to [End]
+**Impact:** [What was affected, how many users]
+
+### Timeline
+- [HH:MM] [Event]
+- [HH:MM] [Event]
+...
+
+### Root Cause
+[What actually caused this]
+
+### Resolution
+[How we fixed it]
+
+### Action Items
+- [ ] [Action] — Owner: [Name] — Due: [Date]
+...
+
+### Lessons Learned
+[What we'll do differently]
+```
+
+### The Work Item
+
+For tickets in any tracking system.
+
+```
+## [Title: Action + Object]
+
+[One sentence: what this accomplishes]
+
+**Scope:**
+- Include: [explicit]
+- Exclude: [explicit]
+
+**Acceptance Criteria:**
+- [ ] [Testable criterion]
+- [ ] [Testable criterion]
+
+**Context/Links:**
+- Related: [links]
+- Blocked by: [ticket]
+```
+
+---
+
+## Anti-Patterns
+
+### Anti-Patterns (avoid these)
+
+- **Throat-Clear** — warming up before getting to the point. Just start.
+- **False Balance** — treating unequal options as equal. Make a call.
+- **Buried Lede** — putting the conclusion at the end. Lead with it.
+- **Infinite Scroll** — no structure. Chunk into Summary / Details / Appendix.
+
+---
+
+## Pattern Selection Guide
+
+| Situation | Pattern |
+|-----------|---------|
+| Quick decision needed | One-pager |
+| Technical decision for review | RFC |
+| Something broke | Incident report |
+| Assigning work | Work item |
+| Persuading stakeholders | Problem-Cause-Solution |
+| Comparing options | Option-Criteria-Recommendation |
+| Explaining a change | What-So What-Now What |
+| Status update | Direct lead + bullets |

package/skills/wickedizer/refs/review.md

@@ -0,0 +1,221 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Review: Quality Validation
+
+How do you know writing is done? This reference provides review criteria and checklists for validating writing quality.
+
+## The Readback Test
+
+**Read your output as if you received it, not as if you wrote it.**
+
+Questions to ask:
+- Do I know what this wants from me?
+- Can I find what I need in 30 seconds?
+- Would I trust this text?
+- Does anything feel off?
+
+If you can't answer yes to all four, revise.
+
+---
+
+## Layered Review Process
+
+### Pass 1: Structural Review (30 seconds)
+
+Scan without reading deeply.
+
+| Check | Question |
+|-------|----------|
+| Title | Does it tell me what this is? |
+| Length | Is it right-sized for the type? |
+| Headings | Can I understand the doc from headings alone? |
+| Scannable | Are key points visible (bold, bullets)? |
+| Organization | Is the point near the top? |
+
+**Stop here if structure fails.** Fix structure before wordsmithing.
+
+### Pass 2: Content Review (2-3 minutes)
+
+Read the content.
+
+| Check | Question |
+|-------|----------|
+| Point clear | Can I state the main point in one sentence? |
+| Complete | Is anything missing that I'd ask about? |
+| Accurate | Are facts, dates, names correct? |
+| Scoped | Is it clear what's in and out of scope? |
+| Actionable | Do I know what happens next? |
+
+### Pass 3: Trust Review (1 minute)
+
+Check for credibility killers.
+
+| Check | Question |
+|-------|----------|
+| Claims supported | Every claim has evidence or is marked as opinion? |
+| No inventions | No made-up stats, quotes, names? |
+| Hedging appropriate | Confident where certain, hedged only where uncertain? |
+| Attribution clear | Sources named or explicitly removed? |
+| AI tells removed | No chatbot artifacts or promotional language? |
+
+### Pass 4: Voice Review (1 minute)
+
+Check for team voice alignment.
+
+| Check | Question |
+|-------|----------|
+| Opening strong | First sentence states the point? |
+| Tone appropriate | Matches the medium and audience? |
+| Consistent terms | Same concept = same word throughout? |
+| Ending strong | Closes with action, decision, or next step? |
+| No fluff | Every sentence earns its place? |
+
+---
+
+## Type-Specific Checklists
+
+### Exec Summary Checklist
+
+- [ ] 5-12 lines maximum
+- [ ] Point in first sentence
+- [ ] Decision/ask explicit
+- [ ] No background section (context integrated)
+- [ ] Numbers over adjectives
+
+### Technical Doc Checklist
+
+- [ ] Context section explains why
+- [ ] Decision stated unambiguously
+- [ ] Alternatives considered (real ones, not straw men)
+- [ ] Tradeoffs explicit
+- [ ] Migration/rollout addressed
+- [ ] Risks identified
+
+### PRD/Requirements Checklist
+
+- [ ] Problem clearly stated
+- [ ] Success criteria measurable
+- [ ] Scope boundaries explicit
+- [ ] Acceptance criteria testable
+- [ ] MUST/SHOULD/MAY used precisely
+- [ ] No marketing language
+
+### Work Item Checklist
+
+- [ ] Title is action + object
+- [ ] One sentence explains what this accomplishes
+- [ ] Scope explicitly lists in/out
+- [ ] Acceptance criteria are checkboxes
+- [ ] Dependencies linked, not just named
+- [ ] Scannable in 10 seconds
+
+### Email/Comms Checklist
+
+- [ ] Subject line has action + topic
+- [ ] First line explains why you're writing
+- [ ] Ask is explicit and visible
+- [ ] One topic per email
+- [ ] Respects reader's time
+
+### Code Comments Checklist
+
+- [ ] Explains why, not what
+- [ ] Doesn't restate the code
+- [ ] Links to issues/decisions if relevant
+- [ ] Terse but complete
+- [ ] No commented-out code
+
+---
+
+## Red Flags
+
+### Immediate Rewrites Needed
+
+| Red Flag | Why It's Bad |
+|----------|--------------|
+| "Hope this helps" | Chatbot artifact |
+| "It's important to note" | Just note it |
+| "Comprehensive solution" | Prove it or cut it |
+| 3+ hedges in a sentence | You're not sure; cut the claim |
+| No ask/action/decision | Why does this exist? |
+| Point in last paragraph | Buried lede |
+
+### Yellow Flags (Check Carefully)
+
+| Yellow Flag | Might Be Fine If... |
+|-------------|---------------------|
+| Longer than expected | Complexity is essential |
+| Technical jargon | Audience is technical |
+| Formal tone | Context requires it |
+| Multiple sections | Each has distinct purpose |
+
+---
+
+## Peer Review Guide
+
+### What to Look For
+
+When reviewing someone else's writing:
+
+1. **Can you state the point?** If not, ask them to clarify.
+2. **What's missing?** What questions would you ask after reading?
+3. **What's unnecessary?** What could be cut without losing meaning?
+4. **Does it match the type?** Is this the right structure for the purpose?
+5. **Would you trust it?** Any credibility concerns?
+
+### How to Give Feedback
+
+```
+// BAD: Vague
+"This is confusing."
+"Needs work."
+"I don't get it."
+
+// GOOD: Specific and actionable
+"I can't tell what decision you need from me."
+"The point seems to be in paragraph 3—can you move it up?"
+"The claim about 40% improvement needs a source."
+```
+
+### How to Receive Feedback
+
+- Assume good intent
+- "Confusing" means confusing to that reader—don't argue
+- Ask for specifics if feedback is vague
+- Not all feedback requires action—use judgment
+
+---
+
+## Definition of Done
+
+### Minimum Bar (All Types)
+
+- [ ] Point is clear and near the top
+- [ ] Structure matches the content type
+- [ ] No facts were invented
+- [ ] Meaning from source is preserved
+- [ ] Contains action, decision, or next step
+
+### Higher Bar (Important Documents)
+
+- [ ] Reviewed by someone else
+- [ ] All red flags addressed
+- [ ] Passes type-specific checklist
+- [ ] Could be understood by someone outside your team
+
+---
+
+## Quick Reference
+
+| Review Type | Time | Focus |
+|-------------|------|-------|
+| Structural | 30 sec | Can I navigate this? |
+| Content | 2-3 min | Is it complete and correct? |
+| Trust | 1 min | Would I believe this? |
+| Voice | 1 min | Does it sound right? |
+
+Total: ~5 minutes for a thorough review.
+
+**If you don't have 5 minutes, do Pass 1 only.** Structural problems matter more than word choice.