wicked-garden 12.27.0

package/skills/swarm/refs/recon-synthesis.md

@@ -0,0 +1,87 @@
+# Recon-first → synthesize → checkpoint
+
+Before an expensive fan-out, spend a little to learn a lot: run a parallel
+**recon wave**, synthesize the findings into a fit-matrix + relevance tiers, and
+**checkpoint scope with the user in a single structured question**. This is the
+swarm's analogue of the `deliberate` skill's "is this real / what's the blast
+radius" lenses, applied across many units at once.
+
+## The recon wave
+
+Dispatch parallel `agents/crew/researcher.md` subagents — read-only, one per
+unit (or one per concept you're trying to map). Each researcher:
+
+- profiles its unit: stack, conventions, test command, risk surfaces, owners,
+- maps where the candidate change would land and what it would touch,
+- writes a **per-unit profile** to disk and returns a concise summary.
+
+Recon agents are read-only, so they fan out freely with no isolation concerns.
+
+## Synthesize
+
+Once recon returns, the orchestrator synthesizes — this is *your* job, not a
+subagent's, because it's the cross-unit view:
+
+1. **Concept catalog** — the set of candidate changes / patterns / findings,
+   each named once with a stable id.
+2. **Per-unit profiles** — one row per unit (already on disk from recon).
+3. **Fit-matrix** — concept × unit. For each cell, does this concept apply to
+   this unit? Mark `GAP` (missing, should add) / `PARTIAL` (half-there) /
+   `ALREADY-COVERED` (unit is already ahead). See `refs/receipts-and-evidence.md`
+   for the honest-marking discipline — do not inflate the matrix.
+4. **Relevance tiers** — rank units/concepts so the fan-out spends effort where
+   it matters: Tier 1 (high impact, do now) → Tier 2 (worth doing) → Tier 3
+   (defer / log). A short true Tier-1 list beats a long speculative one.
+
+## The single checkpoint question
+
+A fan-out is expensive (N implementer + M verifier agents). Before you spend it,
+ask the user **one structured question** that pins scope:
+
+```
+Recon is done. Here's the fit-matrix and tiers:
+  Tier 1 (propose to do now): <units/concepts>
+  Tier 2 (worth doing):       <units/concepts>
+  Tier 3 (defer):             <units/concepts>
+Proceed with Tier 1 as the fan-out scope, or adjust?
+```
+
+One question, structured, scoped. Not a stream of clarifications.
+
+**Under an explicit goal / full latitude, skip the checkpoint and proceed** —
+the user already authorized the spend. (If `AskUserQuestion` is unavailable in
+dangerous mode, fall back to a plain-text question and wait — per the garden's
+AskUserQuestion fallback rule.)
+
+## Scratch-dir layout (the run is auditable from here)
+
+Waves hand off via disk. Lay the scratch dir out so anyone can reconstruct the
+run. The worked example this playbook was distilled from used `.cross-pollination/`;
+any stable scratch dir works (e.g. `.swarm/<run-id>/`):
+
+```
+<scratch>/                       e.g. .cross-pollination/  or  .swarm/<run-id>/
+├── INDEX.md                     top synthesis: concept catalog + fit-matrix + tiers + run status
+├── deferred.md                  deferred-items log — considered-and-rejected, Tier-3, "you're already ahead"
+├── <unit-a>/
+│   ├── profile.md               recon output (stack, conventions, test cmd, risk)
+│   ├── blast-radius.md          implementer impact analysis
+│   ├── plan.md                  what will change, scope held to
+│   ├── diff.patch               (or recorded commit SHA)
+│   ├── test-output.txt          implementer's run (verbatim + exit code)
+│   └── receipt.md               VERIFIER's authoritative receipt (the record of truth)
+├── <unit-b>/ ...
+└── <unit-n>/ ...
+```
+
+`INDEX.md` is the front door — it carries the fit-matrix and per-unit status
+(recon-done → implemented → verified → shipped). The `deferred.md` log is where
+considered-and-rejected items live so they read as **weighed, not missed**.
+
+## Why recon-first
+
+Fanning out before you've profiled the units means every implementer
+re-discovers the same context and you can't tell Tier-1 work from Tier-3 noise.
+A cheap parallel recon wave + one synthesis pass turns the expensive fan-out
+from "discover as you go" into "execute a scoped, tiered plan" — and gives the
+user one clean decision point instead of N mid-flight surprises.

package/skills/swarm/refs/ship-discipline.md

@@ -0,0 +1,90 @@
+# Ship discipline — branch, prove, review, merge, release
+
+Shipping is its own wave, and it only runs **when the user asks**. A swarm
+produces many units of verified work; landing them cleanly without trampling
+each other or skipping the gate is the discipline this ref captures. It composes
+`wicked-garden:worktrees` (isolation + dangling-commit safety) and the gate
+machinery from `refs/receipts-and-evidence.md`.
+
+> **Do not push / open PRs / release until explicitly asked.** The garden's
+> house rule: commit or push only when the user requests it; if on the default
+> branch, branch first. The swarm authors and verifies by default — shipping is
+> opt-in.
+
+## Branch per unit
+
+Each unit lands on **its own branch** — never a shared swarm branch — so units
+ship, review, and roll back independently:
+
+- One branch per unit (e.g. `swarm/<unit-name>/<change>`).
+- **Conventional commits** (`feat:` / `fix:` / `refactor:` / `chore:`) with the
+  body referencing the unit and the receipt. This keeps the provenance check in
+  `agents/crew/reviewer.md` happy (commit messages should reference traceability
+  anchors).
+- **Trust-but-verify every reported commit SHA** (`wicked-garden:worktrees` §1):
+  a subagent's reported SHA can be a dangling commit. Run the ancestry check
+  before you treat the work as on a branch — especially with many implementers
+  committing concurrently.
+
+## CI-green gate (the receipt, again)
+
+A unit does not merge on a green local run alone — the claim is re-derived:
+
+- `/wicked-garden:prove tests-pass --by "<unit test cmd>"` (and `build-clean`,
+  `lint-clean`) must return `satisfied: true, re_derived: true`.
+- For hard-gate units, `--with-attestations` + an independent
+  `wicked-vault attest --opinion pass` (evaluator ≠ implementer).
+- If the unit's repo has a compiled gate (`/wicked-garden:compile`), let
+  `.wicked/gate.py` run in CI — it re-derives through wicked-vault with no
+  garden runtime present.
+
+A red or fail-closed (`gate: "unavailable"`) result blocks the merge. Fix the
+cause; never narrate around a failing gate.
+
+## Independent code review + RESOLVE comments
+
+- Each unit's PR gets an **independent** review — a different agent/human than
+  the implementer (reviewer-separation; `agents/crew/reviewer.md` and the vault
+  both enforce evaluator ≠ creator). For high-stakes units run a
+  `wicked-garden:jam:council` for multi-model perspective.
+- **Resolve every bot/review comment** before merge — address it or reply why
+  it's out of scope. An unresolved comment is an open finding, not noise.
+
+## Clean merge tree
+
+- **Rebase stragglers onto main** before merging so the tree stays linear and
+  each unit's history is legible — don't let a late unit merge a stale base.
+- Merge units in dependency order if any depend on each other (most swarm units
+  are independent by construction — see `refs/fan-out.md`).
+- After merge, confirm the branch's work is actually in main by **ancestry**,
+  not by on-disk worktree presence (`wicked-garden:worktrees` §"authoritative
+  signal") — then delete the branch + log the deletion.
+
+## Tag-driven release + version sync
+
+- Release is **tag-driven**: cut a tag, let CI build/publish from it.
+- **Version-sync** anything that must agree (package manifest, lockfile, any
+  embedded version constant) in the same release commit — a drifted version is a
+  silent ship bug.
+
+## Root causes + second-order regressions
+
+- Fix **root causes**, not symptoms (the verify wave will catch a symptom-patch
+  that doesn't re-derive).
+- Watch for the **second-order regression** the change itself can introduce.
+  Worked example: a CI workflow edit that quietly **drops a test gate** — the
+  suite goes "green" because it stopped running, not because it passed. The
+  verifier's over-claim check (`refs/independent-verification.md` §3) is exactly
+  what catches this: re-run from clean and confirm the gate still actually runs.
+
+## The ship checklist (per unit)
+
+```
+[ ] on its own branch, conventional commits, SHA verified by ancestry
+[ ] /wicked-garden:prove → satisfied + re_derived for tests/build/lint
+[ ] hard-gate units: independent wicked-vault attest --opinion pass
+[ ] independent review done; all review/bot comments resolved
+[ ] rebased onto current main; clean tree
+[ ] (release) tag cut; versions synced
+[ ] branch merged, confirmed in main by ancestry, then deleted + logged
+```

package/skills/wickedizer/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: wicked-garden-wickedizer
+context: fork
+description: |
+  Writing humanizer / AI-tell remover (the team's house writing-cleanup skill).
+  Use when writing, rewriting, or humanizing content: strips AI tells (fluff, hedging,
+  promo language, chatbot artifacts) while preserving meaning, and aligns output to a
+  direct, practical, action-oriented team voice.
+
+  Use when: humanizing AI-sounding prose, "remove AI tells", "make this sound human",
+  drafting a PR description or commit message, or aligning written output to team voice.
+  Aliases: humanize, humanizer, dejargonize, writing-cleanup.
+portability: portable
+status: experimental
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+
+# Wickedizer: Clear, Credible, Human Writing
+
+You are rewriting for **trust** and **clarity**, not for "vibes."
+
+Your job:
+- Remove AI-generated tells (fluff, hedging, promo language, chatbot artifacts)
+- Preserve meaning, constraints, and domain terms
+- Align to team voice: direct, pragmatic, outcome-driven
+- NEVER invent facts, citations, names, or numbers
+
+## When This Skill Applies
+
+**Invoke automatically when:**
+- Writing or rewriting prose (emails, memos, exec summaries, PRDs, POVs)
+- Producing slide text or bullets
+- Writing work items (epics/stories/tasks/bugs in Jira, Linear, GitHub Issues, Azure DevOps, etc.)
+- Drafting PR descriptions, commit messages, ADRs/RFCs, design docs
+- Writing code comments, docstrings, READMEs, runbooks
+
+## Non-Negotiables
+
+1. **Do not change meaning** - Preserve commitments, constraints, scope, decisions
+2. **Do not add facts** - No invented stats, quotes, names, dates, attributions
+3. **Keep useful structure** - Headings, bullets, tables that aid scanning
+4. **Keep terminology stable** - Same concept = same name everywhere
+5. **Match medium + audience** - Slack ≠ PRD ≠ exec memo
+
+## Operating Process
+
+### Step 0: Classify the Artifact
+Pick ONE: `exec-summary` | `technical-doc` | `prd-requirements` | `work-item` | `email-comms` | `slide-bullets` | `code-comments` | `mixed`
+
+→ See [refs/artifact-types.md](refs/artifact-types.md) for mode-specific rules.
+
+### Step 1: Extract Immutables
+Identify and preserve:
+- Facts, dates, numbers, names, owners
+- Decisions, constraints, scope boundaries
+- Domain terms and key nouns
+- Acceptance criteria / definitions of done
+
+### Step 2: De-AI Pass
+Remove:
+- Chatbot artifacts ("hope this helps", validation filler)
+- Promotional language and significance inflation
+- Hedge stacking ("could potentially possibly")
+- Vague attributions ("experts say")
+- Cadence uniformity (same rhythm every sentence)
+
+→ See [refs/de-ai-pass.md](refs/de-ai-pass.md) for detection patterns.
+
+### Step 3: Clarity Pass
+- Convert abstract nouns into actions
+- Replace vague verbs with specific ones
+- Ensure reader can answer: **What changed? Why? Who owns it? What's next?**
+
+### Step 4: Voice Pass
+Apply team voice defaults:
+- Assertive opening sentence with limited bold
+- Scannable structure: short paragraphs, real bullets
+- Consistent terms (no synonym cycling)
+- Close with next steps / decision points
+
+→ See [refs/voice-profile.md](refs/voice-profile.md) for full voice guide.
+
+### Step 5: Trust Check
+Before output, verify:
+- [ ] No added facts, citations, names, or stats
+- [ ] Meaning and constraints preserved
+- [ ] Structure appropriate for medium
+- [ ] Output contains at least one: decision, tradeoff, next step, open question, or measurable outcome
+
+→ See [refs/failure-modes.md](refs/failure-modes.md) for common problems.
+
+## Quick Reference: What to Remove
+
+| Pattern | Fix |
+|---------|-----|
+| "Additionally / Furthermore / Moreover" spam | Delete most transitions |
+| "Pivotal / transformative / game-changing" | Remove or prove |
+| "Not just X, but Y" scaffolding | State directly |
+| Rule-of-three when 2 is correct | Use real count |
+| "Experts agree" without naming | Cite or delete |
+| "Hope this helps!" | Delete |
+
+## Quick Reference: What to Keep
+
+| Element | When |
+|---------|------|
+| Bullets and lists | When they aid scanning |
+| Technical terms | When precise |
+| Numbers and dates | Always (don't generalize) |
+| Named constraints | Always |
+| Scope boundaries | Always |
+
+## Output Format
+
+Return:
+1. The rewritten content
+2. Optional **Change Log** (3-8 bullets) if helpful:
+   - Removed fluff
+   - Clarified claims
+   - Preserved constraints
+   - Adjusted structure
+
+## Flexibility Note
+
+These are defaults, not laws. Override when:
+- Source material is intentionally casual or formal
+- Audience expects different tone (legal, marketing)
+- Context requires adaptation
+
+The goal is **credible and specific**, not rigid adherence. Situation matters more than rules.
+
+## References
+
+**Core Process:**
+- [Voice Profile](refs/voice-profile.md) - Tone, sentence structure, ending strong
+- [De-AI Pass](refs/de-ai-pass.md) - Detecting and removing AI tells
+- [Artifact Types](refs/artifact-types.md) - Mode-specific guidance
+
+**Principles:**
+- [Structure](refs/structure.md) - Document architecture and organization
+- [Complexity](refs/complexity.md) - KISS, YAGNI, DRY for writing
+- [Patterns](refs/patterns.md) - Reusable templates and structures
+
+**Quality:**
+- [Review](refs/review.md) - Validation checklists by type
+- [Failure Modes](refs/failure-modes.md) - Common problems and fixes

package/skills/wickedizer/refs/artifact-types.md

@@ -0,0 +1,238 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Artifact Types: Mode-Specific Guidance
+
+Different document types have different constraints. This reference provides specific guidance for each artifact type wickedizer handles.
+
+## Artifact Classification
+
+Before rewriting, classify the artifact. This determines structure, tone, and what counts as "good."
+
+| Type | Primary Goal | Length Constraint |
+|------|--------------|-------------------|
+| exec-summary | Decision support | 5-12 lines |
+| technical-doc | Enable correct implementation | As needed, well-structured |
+| prd-requirements | Specify what to build | Clear scope, explicit criteria |
+| work-item | Enable task execution | Scannable, all context present |
+| slide-bullets | Support verbal presentation | 6x6 optional, clarity mandatory |
+| code-comments | Explain non-obvious decisions | Terse, meaningful |
+| email-comms | Drive action or share info | Reader's time is precious |
+
+---
+
+## exec-summary
+
+### Purpose
+Help executives make decisions quickly. They're reading 20 of these today.
+
+### Structure
+```
+[One stance sentence - what this is and why it matters]
+
+- What's happening
+- Why now / why this matters
+- Key risks or tradeoffs
+- What we need (decision/approval/resources/timeline)
+```
+
+### Rules
+- 5-12 lines maximum unless specifically asked for more
+- No background section - integrate context into bullets
+- Decision or ask must be explicit
+- Numbers beat narratives
+
+### Example
+
+**Before (typical AI output):**
+> The engineering team has been conducting a comprehensive evaluation of our current authentication infrastructure. After extensive analysis, we've identified several opportunities for improvement that could significantly enhance our security posture while also improving the user experience...
+
+**After:**
+> **Auth system migration** needs approval by Friday to hit Q2 security audit.
+>
+> - Current: session tokens, 3 known vulnerabilities, audit finding
+> - Proposed: JWT with refresh rotation, fixes all 3 CVEs
+> - Risk: 2-week migration, some legacy clients need updates
+> - Ask: Budget approval for $40k contractor support
+
+---
+
+## technical-doc (ADR/RFC/Design Doc)
+
+### Purpose
+Enable correct implementation and future understanding. These docs outlive their authors.
+
+### Required Sections
+1. **Context** - Why are we here? What problem?
+2. **Decision** - What we're doing (clear, unambiguous)
+3. **Options Considered** - 2-3 alternatives with brief tradeoffs
+4. **Tradeoffs** - What we're giving up, what we're gaining
+5. **Rollout / Risks** - How we ship, what could go wrong
+
+### Rules
+- Preserve rigor - don't simplify technical content
+- "Comprehensive" claims need coverage proof
+- Diagrams referenced should exist or be noted as needed
+- Future reader is the audience, not current team
+
+### Anti-patterns
+- Decisions buried in prose
+- Options considered that are obviously bad (straw men)
+- Missing rollback plan
+- "We decided X" without the why
+
+---
+
+## prd-requirements
+
+### Purpose
+Specify what to build so engineering can estimate and execute.
+
+### Key Elements
+- Problem statement (what pain, for whom)
+- Success criteria (measurable)
+- Scope (what's in, what's explicitly out)
+- Acceptance criteria per feature
+- Dependencies and constraints
+
+### Language Precision
+| Keyword | Meaning |
+|---------|---------|
+| MUST | Non-negotiable requirement |
+| MUST NOT | Prohibited |
+| SHOULD | Expected unless justified exception |
+| MAY | Optional, nice to have |
+
+### Rules
+- Avoid marketing tone - this is a spec, not a pitch
+- Acceptance criteria must be testable
+- "User can..." not "Users will be empowered to..."
+- Scope boundaries explicit
+
+---
+
+## work-item (Epic/Story/Task/Bug)
+
+Applies to: Jira, Linear, GitHub Issues, Azure DevOps, Shortcut, Asana, or any work tracking system.
+
+### Purpose
+Enable someone to pick this up and execute without asking questions.
+
+### Structure
+```
+[One sentence: what this accomplishes]
+
+**Scope:**
+- Include: [explicit list]
+- Exclude: [explicit list]
+
+**Acceptance Criteria:**
+- [ ] Criterion 1 (testable)
+- [ ] Criterion 2 (testable)
+
+**Dependencies:**
+- Blocked by: [item] - [brief reason]
+- Blocks: [item]
+```
+
+### Rules
+- Scannable in 10 seconds
+- All context in the item (don't rely on memory or tribal knowledge)
+- Acceptance criteria are checkboxes, not prose
+- Link dependencies, don't just name them
+
+### Anti-patterns
+- "As a user, I want..." when it doesn't help
+- AC that require interpretation
+- Missing scope boundaries
+- Dependencies named but not linked
+
+---
+
+## slide-bullets
+
+### Purpose
+Support a presenter. Slides are not documents.
+
+### Rules
+- One idea per bullet
+- 6x6 is guideline, not law
+- Sentence fragments preferred over full sentences
+- No sub-sub-bullets
+
+### Structure
+- Lead with the point
+- Evidence or example
+- Implication if not obvious
+
+### Anti-patterns
+- Bullets that are paragraphs
+- Reading the slide verbatim
+- Decorative bullets (just filling space)
+- Nested lists 3 levels deep
+
+---
+
+## code-comments
+
+### Purpose
+Explain what isn't obvious from reading the code.
+
+### What to Comment
+- **Why** decisions were made
+- Non-obvious constraints or tradeoffs
+- Workarounds with context (link to issue if applicable)
+- Performance implications that aren't visible
+- Security considerations
+
+### What NOT to Comment
+- What the code does (code should be readable)
+- Restating the function name
+- Changelog in comments (use git)
+- Commented-out code (delete it)
+
+### Examples
+
+**Bad:**
+```typescript
+// Increment counter
+counter++;
+```
+
+**Good:**
+```typescript
+// Retry limit set to 3 based on p99 latency analysis - higher causes timeout cascade
+const MAX_RETRIES = 3;
+```
+
+---
+
+## email-comms
+
+### Purpose
+Get a response, share information, or document a decision.
+
+### Structure
+- **Subject line:** Action + Topic + Deadline (if applicable)
+- **First line:** Why you're writing
+- **Body:** What they need to know
+- **Close:** What you need from them (explicit ask)
+
+### Rules
+- Respect inbox triage - get to point fast
+- Bold or bullet the ask
+- One email = one topic (usually)
+- Reply threads: quote only relevant context
+
+### Anti-patterns
+- Burying the ask in paragraph 4
+- "I hope this email finds you well"
+- "Please advise" (advise on what?)
+- CC everyone, ask no one
+
+---
+
+## Mixed Artifacts
+
+When a document spans types (e.g., PRD with exec summary), apply each section's rules to the relevant parts. The exec summary follows exec-summary rules even when embedded in a larger doc.