@diottodev/runic 1.0.0 → 1.1.0

package/productivity/capture/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: capture
+description: "Captures and organizes chaotic brain dumps into a structured, actionable system with zero information loss. Use this skill whenever the user says 'capture this', 'brain dump', 'let me dump some ideas', 'I've got a bunch of thoughts', 'here's everything on my mind', 'idea dump', 'let me get this out of my head', 'I need to organize my thoughts', 'here's what I'm thinking', or any variation where someone is unloading a messy stream of ideas, tasks, thoughts, and plans wanting them turned into something coherent. Also trigger when the user pastes or dictates a long, unstructured block of mixed ideas — even without the exact phrase — the intent is the same. Fast-to-action by design: no upfront intake. Output is four sections (Projects/Ideas, Tasks, Connections, How I Can Help) ending with a directive question. Asks at most one mid-organization clarifying question when a single item is genuinely ambiguous between task and project."
+license: MIT
+metadata:
+  source_spec: "megaprompts/05-capture-megaprompt.md"
+  build_pattern: "Path B (direct conversion)"
+  version: 1.0.0
+---
+
+# Capture — Brain-Dump Organizer
+
+A fast-to-action skill for transforming unstructured streams of mixed thoughts, tasks, and ideas into a clean four-section actionable system with zero information loss.
+
+## Invocation Triggers
+
+**Explicit phrases** (any of):
+- "brain dump"
+- "capture this"
+- "let me dump some ideas"
+- "I've got a bunch of thoughts"
+- "here's everything on my mind"
+- "idea dump"
+- "let me just get this out of my head"
+- "I need to organize my thoughts"
+- "here's what I'm thinking"
+
+**Implicit signals** (no phrase, but the intent is unmistakable):
+- User pastes or dictates a long unstructured block of mixed ideas, tasks, plans
+- Multiple unrelated thoughts in one message without organizing framing
+- A wall of bullet-y text covering 3+ unrelated topics
+
+When you detect an implicit trigger, run the skill. Do NOT ask "do you want me to organize this?" first — the dump itself IS the request.
+
+## Operating Principles (All Five Apply Always)
+
+1. **Capture everything.** Zero loss. Trivial items go in; the user prunes later. Never silently drop something because it "seemed unimportant".
+2. **Preserve voice.** If the user said "build something crazy with AI", do NOT restate as "Explore innovative AI-driven solutions." Keep the energy and the casual register. See `references/voice_preservation.md` for concrete anti-patterns.
+3. **Match output complexity to input.** A 5-task dump does NOT get forced into 4 elaborate sections. See `references/complexity_matching.md` and the Compressed Output Pattern below.
+4. **Be honest about ambiguity.** If you're unsure what something means, flag it. Don't guess silently.
+5. **No action without approval.** The ONLY immediate action is the organization itself. Every offer in Section 4 waits for the user's explicit pick.
+
+## Grill-Me Mid-Organization Clarifier
+
+Capture is fast-to-action by design. **No upfront intake.** The dump is enough — start organizing immediately.
+
+The grill-me discipline applies as a **single mid-organization clarifying question**, asked **only when** one item in the dump is genuinely ambiguous between *task* and *project*, AND the misclassification would meaningfully change the output:
+
+> **Quick clarification — one item in your dump could go either way. Is [X] a one-shot task or a multi-step project?**
+>
+> *Why I'm asking:* If I guess wrong on a borderline item I either bury a project as a task or inflate a task into a project that doesn't need the structure. One question per dump prevents that.
+
+**Stop condition:** Max 1 clarifying question per dump. After the answer (or if no clarification was needed), deliver the four (or compressed) sections.
+
+If the dump is unambiguous, skip the clarifier entirely.
+
+**Anti-pattern (do not do this):** asking 3 clarifying questions up front. That breaks the dump-and-organize flow that makes capture useful.
+
+## Section 1: Projects & Ideas
+
+Cluster related items into themed projects when natural clustering exists. This section also holds:
+- Standalone creative sparks
+- Half-formed concepts
+- "What if" thoughts
+- Embedded decisions (`Decide: X or Y`) and open questions (`Q: ...`) — kept WITHIN the relevant project, NOT extracted into a separate top-level category
+
+**Format per project:**
+
+```
+### {Project name in user's voice}
+
+- {component / sub-idea}
+- {component}
+- Q: {open question this project needs answered}
+- Decide: {decision this project requires}
+```
+
+Use the user's words for the project name. If the user wrote "ai dating app for ferrets", do NOT rename it to "AI-Powered Pet Companion Platform".
+
+## Section 2: Tasks
+
+Flat, scannable, action-oriented. Includes:
+- Explicit todos
+- Decisions framed as `Decide: ...`
+- Open questions framed as `Resolve: ...`
+
+If a task belongs to a project from Section 1, append `[Project: X]` to link it — but don't repeat the project's context.
+
+**Format:**
+
+```
+- {task in imperative voice}  [Project: X if related]
+- Decide: {decision}  [Project: X if related]
+- Resolve: {open question}
+- ...
+```
+
+## Section 3: Connections
+
+This is where the skill earns its keep — and where **fabrication is forbidden**.
+
+**Workflow:**
+
+1. **Inventory the workspace** — Glob for filename patterns matching dump keywords, Grep for content matches, read the top-level directory structure. Use `scripts/workspace_inventory.py` to do this deterministically.
+2. **Match dump items to existing content** — files / folders relating to dumped items, prior thinking in documents, in-progress projects with overlap.
+3. **Surface dependencies within the dump** — items that affect each other, themes, ordering implications.
+4. **Be honest about inaccessibility** — if you can't inspect the workspace (no filesystem available, MCP not connected), say so explicitly. Do NOT make up plausible-sounding connections.
+
+**Hard rule:** NEVER fabricate connections. Only surface ones actually found by Glob/Grep/Read. If no real connections exist:
+
+> **Connections:** No connections found — workspace inventory clean.
+
+If the workspace is inaccessible:
+
+> **Connections:** No workspace accessible from here. If you're running this from Claude Code or have a project with files attached, I can fill this in. Want to share where this work lives?
+
+See `references/workspace_detection.md` for the per-context detection-tactic catalog.
+
+## Section 4: How I Can Help
+
+**Concrete offers, not abstract possibilities.** Every offer specifies what would be produced AND where it would go.
+
+| ✅ Right pattern | ❌ Anti-pattern |
+|---|---|
+| "I can research Consensus MCP integration patterns and give you 3 options. Output: `docs/consensus-options.md`." | "You might want to look into integration approaches." |
+| "I can draft the Q3 launch plan as a 1-pager. Output: chat reply, then `docs/q3-launch.md` if you want it filed." | "Maybe think about Q3 planning." |
+| "I can scaffold the new auth module with the existing pattern from `src/users/`. Output: 4 files in `src/auth/`." | "We could explore auth options." |
+
+End with the directive question:
+
+> **Which of these should I tackle?**
+
+## Compressed Output Pattern
+
+When the dump has **5 or fewer items** and items are **unrelated** (no natural clustering), drop the 4-section format and use compressed:
+
+```
+## What I heard
+
+- {item}
+- {item}
+- {item}
+- ...
+
+## How I can help
+
+- {concrete offer with what + where}
+- {concrete offer with what + where}
+
+Which should I tackle?
+```
+
+The trigger is the `complexity_estimator.py` recommendation OR your judgment when no clusters exist. See `references/complexity_matching.md` for worked examples of when each format applies.
+
+## Workspace Detection Strategy
+
+| Context | Detection method |
+|---|---|
+| Claude Code CLI | Glob for files matching dump keywords; Grep for content matches; read top-level structure. Use `scripts/workspace_inventory.py`. |
+| Claude.ai with project | Check project knowledge files for thematic overlap. List file titles; surface matches by keyword. |
+| Connected tools (Notion, Drive, etc.) | Search via MCP if available. |
+| No accessible workspace | State the limitation explicitly; ask user about their setup; do NOT fabricate. |
+
+## Approval Gate
+
+After the four (or compressed) sections are delivered:
+
+- **Wait for the user's explicit pick** before doing anything else.
+- If the user says "go" without picking a specific offer: honor it, but explicitly note any items you weren't 100% sure about so they can correct.
+- The organization itself is the only auto-action. Every Section 4 offer requires green light.
+
+## Error Handling
+
+| Situation | Behavior |
+|---|---|
+| Workspace inaccessible | State this; skip Section 3 or surface "no workspace accessible" + ask about setup |
+| Dump is very short (3-5 items) | Use compressed output; don't force 4 sections |
+| Items are highly ambiguous | Flag in output, ask up to 1 clarifier (or skip clarifier and surface ambiguity in delivery) |
+| Dump contains sensitive info | Acknowledge but don't echo verbatim if user asks for organization without quoting |
+| Conflicting items in the dump | Surface the conflict in Section 1 or 3 explicitly (`Conflict: X says A, Y says B`) |
+| User says "go" before approval | Honor it, but explicitly note items you weren't sure about |
+
+## Tooling
+
+| Script | Role |
+|---|---|
+| `scripts/workspace_inventory.py` | Glob+Grep helper for Section 3. `python workspace_inventory.py --root . --keywords "k1,k2"` returns matches by keyword + folder structure. |
+| `scripts/dump_classifier.py` | Regex-classifies each dump line into `task` / `decision` / `question` / `idea` / `project-component`. Heuristic — override with judgment. |
+| `scripts/complexity_estimator.py` | Counts items, detects clustering signal, recommends `format=full` or `format=compressed`. |
+
+## References
+
+- `references/workspace_detection.md` — context-specific detection tactics (CLI / web / MCP / inaccessible)
+- `references/voice_preservation.md` — corporate-speak anti-patterns with concrete examples
+- `references/complexity_matching.md` — compressed vs full output, worked examples
+
+## Anti-Patterns To Reject
+
+- Fabricating workspace connections that weren't actually Glob/Grep-verified
+- Dropping items deemed "trivial" — capture everything, let the user prune
+- Corporate-ifying the user's casual language
+- Forcing 4-section structure when input is small (5 simple tasks doesn't need it)
+- Acting on Section-4 offers immediately without approval
+- Splitting decisions/questions into a separate top-level category instead of embedding them in the relevant project
+- Vague Section-4 offers ("you might want to consider…")
+- Asking 3+ clarifying questions up front (breaks fast-to-action)
+
+---
+
+**Version:** 1.0.0
+**Source spec:** [`megaprompts/05-capture-megaprompt.md`](../../../../megaprompts/05-capture-megaprompt.md)
+**Build pattern:** Path B (direct conversion). Re-grill with `/cs:grill-with-docs` if drift between spec and implementation surfaces.

package/productivity/handoff/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: handoff
+description: "Compact the current conversation into a handoff document for another agent to pick up. Save to a user-configured location (OS temp, home folder, or per-project .handoff/), redact secrets before write, suggest skills for the next session, and auto-load the latest handoff on the next SessionStart. First-run setup asks where to save so the project folder never gets cluttered. Use when the user says 'hand this off', 'handoff doc', 'summarize this for a new session', 'compact this conversation', 'I'm ending this session', 'pick this up later', or any variation signaling intent to pass work to a fresh agent. Also trigger on implicit signals: the user announcing they're switching machines, ending the day mid-task, or context is growing long without a natural stopping point."
+license: MIT
+argument-hint: "What will the next session be used for?"
+metadata:
+  version: 1.0.0
+  voice: "Matt Pocock — no-duplication, reference-existing-artifacts, tailored to next-session focus"
+  inspired_by: "https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff"
+---
+
+# Handoff
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS — not the current workspace.
+
+Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
+
+## Invocation Triggers
+
+**Explicit phrases** (any of):
+- "hand this off"
+- "handoff doc"
+- "summarize this for a new session"
+- "compact this conversation"
+- "I'm ending this session"
+- "pick this up later"
+- "wrap this up for tomorrow"
+- "save this for the next session"
+
+**Implicit signals** (no phrase, but the intent is unmistakable):
+- User announces they're switching machines or stopping for the day mid-task
+- Conversation context is growing long without a natural stopping point
+- User says "let me come back to this" or "I'll continue this later"
+
+When you detect an implicit trigger, propose the handoff before running it: *"Want me to write a handoff for the next session?"* — never run it silently.
+
+## First-Run Setup
+
+On first invocation, the skill asks where to save handoffs so the project folder never gets cluttered. Setup is offered once via *"Run setup now? (Y/n)"* — answering N uses OS-temp defaults for this run and never re-prompts. The user can rerun setup any time via `/cs:handoff-setup`.
+
+See [references/configuration.md](references/configuration.md) for the full config field reference.
+
+## Output Path
+
+The save location is read from the user's config (`~/.config/handoff/config.json`, or the project-local `.handoff/config.json` if present). When no config exists and the user declined setup, fall back to:
+
+```bash
+mktemp -t handoff-XXXXXX.md
+```
+
+Read the file before you write to it.
+
+## Section Template
+
+The handoff doc has five sections. Use these exact headers:
+
+- **Goal of next session** — from the user's argument, or inferred from the most recent thread of the conversation.
+- **State of play** — what's done, what's in flight, what's blocked. Reference artifacts, do not paste them.
+- **Open decisions** — what the next agent must decide before continuing.
+- **Skills to use** — concrete list of 3-5 skills the next session should invoke, each with a one-line *why*.
+- **Artifacts** — paths/URLs to PRDs, plans, ADRs, issues, branches, PRs. Do not duplicate their contents.
+
+See [references/handoff_structure.md](references/handoff_structure.md) for a worked example.
+
+## The Agent's Job
+
+Filling in the five sections is the agent's job, not the script's. Follow [references/handoff_prompt.md](references/handoff_prompt.md) as a mandatory checklist:
+
+> For each topic discussed in the conversation, decide explicitly: *include in State of play / log as an Open decision / drop with reason.*
+
+Free-handing the summary leads to rosy progress reports and dropped blockers. The checklist prevents that.
+
+## Anti-Patterns
+
+Matt's no-duplication discipline made concrete:
+
+- **Do not paste the diff.** Reference the branch or PR.
+- **Do not retype the PRD.** Link to its path.
+- **Do not summarise what's already in the commit message.** Link to the commit hash.
+- **Do not list 20 skills.** Pick the 3-5 the next session actually needs.
+- **Do not narrate every message in the conversation.** Compress to State + Decisions.
+
+See [references/deduplication_discipline.md](references/deduplication_discipline.md) for the full list.
+
+## Redaction
+
+Before saving, the linter scans the draft for secrets and PII. In strict mode (default) it blocks save on findings; in warn mode it flags inline and saves anyway.
+
+Redact:
+- API keys, OAuth tokens, JWT tokens
+- Passwords and DB connection strings
+- `-----BEGIN ... PRIVATE KEY-----` blocks
+- `.env`-style `KEY=value` lines containing secrets
+- Email addresses, phone numbers, names of unrelated third parties
+- Internal URLs containing tokens or session IDs
+
+See [references/redaction_checklist.md](references/redaction_checklist.md) for the full pattern list and manual-review steps for what regex cannot catch.
+
+## SessionStart Auto-Load
+
+When the plugin is installed, a `SessionStart` hook scans the configured save location for the most recent handoff (within the retention window) and surfaces it to the new session as `<handoff_from_previous_session>` data. The next agent reads it as context, not as instructions — suggested actions must be verified against current state before executing.
+
+Disable per-session with `HANDOFF_SESSIONSTART=0`.
+
+## SessionEnd Reminder
+
+A paired `SessionEnd` hook checks whether a recent handoff exists when the session is ending. If none does (or the most recent is older than 30 minutes), it prints a one-line reminder so the user is prompted to write one before context is lost.
+
+The hook cannot prompt interactively or block session end — it surfaces text in the session log.
+
+Disable per-session with `HANDOFF_SESSIONEND=0`.
+
+## Refreshing an Existing Handoff
+
+When work continues past the original handoff time, refresh in place instead of creating a new file:
+
+```bash
+python3 scripts/handoff_template_generator.py --refresh --goal "<updated goal>"
+```
+
+Prints the path of the most recent handoff. The agent edits it directly. Keeps the save location uncluttered and ensures the SessionStart hook always loads the up-to-date version.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `setup.py` | First-run Q&A — save location, retention, redaction strictness, git-context, recommender scope. |
+| `handoff_template_generator.py` | Writes the 5-section scaffold at the configured path. `--refresh` reuses the most recent handoff instead of creating a new file. |
+| `redaction_linter.py` | Scans the draft for secrets/PII before save. Exit 1 on findings in strict mode. |
+| `handoff_self_check.py` | Fidelity check — flags empty Goal, State bullets without artifacts, missing Decisions when git is dirty, too few/many Skills, inline content in Artifacts. Run before the linter. |
+| `skill_recommender.py` | Suggests 3-5 skills for the next session based on goal text + repo scan. |
+| `cleanup.py` | Deletes scaffolds older than the retention window. mtime-guarded — never deletes a handoff the user edited. |
+| `config_loader.py` | Shared helper: read project config → global config → defaults. |
+
+## Slash Commands
+
+- `/cs:handoff [optional next-session description]` — generate the handoff.
+- `/cs:handoff-setup` — reconfigure save location, retention, redaction.
+
+## Agent
+
+`cs-handoff-author` — Matt-voice persona orchestrating the skill. Terse, no-duplication, references-not-copies.
+
+## Examples
+
+### Example 1 — explicit invocation with a goal
+
+```
+User: /cs:handoff "finish wiring the redaction linter and open a draft PR"
+```
+
+The skill walks the mandatory checklist, generates a 5-section scaffold, fills it from the conversation, runs the redaction linter, and saves to the configured location. See `assets/example_handoff.md` for a complete worked example.
+
+### Example 2 — implicit trigger
+
+```
+User: I'm packing up for the day, let me come back to this tomorrow.
+```
+
+Detect the implicit signal. Propose before running: *"Want me to write a handoff for the next session?"* — never silently. On confirmation, proceed as Example 1 with an inferred goal.
+
+### Example 3 — first-run setup
+
+```
+User: /cs:handoff "ship the migration"
+Skill: Run setup now? (Y/n)
+User: Y
+[setup walks 5 questions: save location, retention, redaction strictness, git context, recommender scope]
+Skill: Config saved to ~/.config/handoff/config.json. Continuing with handoff for: ship the migration.
+```
+
+If the user answers N, the skill writes a sentinel and uses defaults (OS temp dir, 7-day retention, strict redaction). The prompt never re-appears.
+
+### Example 4 — SessionStart auto-load
+
+On the next session, the SessionStart hook scans the configured save location, finds the most recent handoff, and surfaces it as `<handoff_from_previous_session>` data. The next agent reads it as context, not instructions.
+
+## Usage
+
+| Step | Command |
+|---|---|
+| First-run setup | `/cs:handoff-setup` (or answer Y on first `/cs:handoff`) |
+| Generate a handoff | `/cs:handoff [goal]` |
+| Reconfigure later | `/cs:handoff-setup --reconfigure` |
+| Project-specific config | `/cs:handoff-setup --project` |
+| Disable SessionStart hook | `HANDOFF_SESSIONSTART=0` (per session) |
+
+---
+
+**Version:** 1.0.0
+**Inspired by:** [Matt Pocock's handoff](https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff) (MIT).

package/productivity/inbox-setup/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: inbox-setup
+description: "One-time setup skill that builds a personalized inbox triage knowledge base via interactive interview. Interviews the user about their email patterns, business context, reply style, and priorities using grill-me discipline (one question at a time, forcing format where possible, dependency-ordered, each question explains why I'm asking), then generates the knowledge base files that power the companion 'inbox-triage' skill. Run this once before using inbox-triage for the first time. Re-run when business, pricing, or priorities change significantly. Triggers: 'set up my inbox', 'configure inbox triage', 'set up my email system', 'configure email triage', 'build my email knowledge base', 'initialize email management', 'set up inbox triage', 'onboard email triage', or any variation where someone wants to get the email triage system running for the first time."
+license: MIT
+metadata:
+  source_spec: "megaprompts/06-inbox-setup-megaprompt.md"
+  build_pattern: "Path B (direct conversion)"
+  paired_with: "inbox-triage (shared 7-file KB contract)"
+  version: 1.0.0
+---
+
+# Inbox-Setup — Email Triage Onboarding
+
+> **Paired with `inbox-triage`.** This skill writes the 7-file knowledge base at `${WORKSPACE}/Email/` that `inbox-triage` reads on every run. The file contracts (names, sections, fields) MUST match between the two skills exactly. See [`references/kb_file_contract.md`](references/kb_file_contract.md).
+
+Run once (or re-run when business/priorities change). Interview the user about their email patterns, business context, reply style, and priorities. Generate the structured knowledge base in `${WORKSPACE}/Email/` that captures everything `inbox-triage` needs to process the inbox effectively.
+
+## Invocation Triggers
+
+- "set up my inbox"
+- "configure inbox triage"
+- "set up my email system"
+- "configure email triage"
+- "build my email knowledge base"
+- "initialize email management"
+- "set up inbox triage"
+- "onboard email triage"
+
+## Conduct Discipline
+
+**Do NOT generate all files at once.** Walk through the 8 sections one at a time. Each section commits its file(s) before moving on. Partial completion (e.g., user drops off mid-interview) still produces a usable partial KB.
+
+Grill-me discipline applies throughout:
+
+- **One question per turn.** Never bundle. Even across section boundaries.
+- **"Why I'm asking" on every question** — so users can answer well.
+- **Forcing format where possible.** Multi-choice > open-ended.
+- **Dependency-ordered.** Q2 depends on Q1; downstream sections depend on upstream.
+
+See [`references/grill_me_section_walk.md`](references/grill_me_section_walk.md) for the 8-section discipline detail.
+
+## Knowledge Base Contract — Files To Produce
+
+Exactly these files at `${WORKSPACE}/Email/`:
+
+| File | Purpose | Required? |
+|---|---|---|
+| `email-taxonomy.md` | Classification system + report preferences | **Yes** |
+| `email-patterns.md` | Reply voice, tone, templates, hard rules | **Yes** |
+| `evaluation-framework.md` | Decision tree for opportunity emails | Only if user receives pitches/opportunities |
+| `rate-card.md` | Pricing, terms, negotiation posture | Only if user has pricing |
+| `blocklist.md` | Auto-skip senders + learned decline patterns | **Yes** (seeded, grows over time) |
+| `tracker.md` | Active follow-ups, overdue items, deadlines | **Yes** (starts mostly empty) |
+| `triage-log/` | Directory for per-run logs | **Yes** (created empty) |
+
+The contract is identical to what `inbox-triage` expects — see [`references/kb_file_contract.md`](references/kb_file_contract.md) for the full spec.
+
+## Stop Condition (Full Interview)
+
+~25–31 questions total across the 8 sections (depending on skip-logic). Hard ceiling: 35 questions including all sub-clarifications. Section 4 (Evaluation Framework) is skipped entirely when Section 1 surfaced no opportunity-email category, dropping the total by 6 questions and the rate-card file. After Section 8's confirmation + handoff message, intake is closed — **never re-open it**. To change preferences later, the user re-runs the skill (which detects existing files and asks per-file: replace / merge / skip). The grill-me one-at-a-time rule applies across section boundaries: do NOT batch questions even when moving from S{n} to S{n+1}.
+
+## Section 1: The Big Picture
+
+Six grill-me questions, one at a time:
+
+- **S1.Q1:** "What do you do? Give me your role and business in 1–2 sentences. *Why I'm asking:* Context shapes what email patterns to expect — a solo creator's inbox looks nothing like an enterprise PM's."
+- **S1.Q2:** "What dominates your inbox? Pick the top 1–2: sales pitches / client work / internal team / newsletters / customer support / financial / other. *Why I'm asking:* Dominant categories drive the taxonomy."
+- **S1.Q3:** "Rough volume split — e.g., '60% business inquiries, 20% ops, 20% noise'. *Why I'm asking:* The split tells me where to focus triage effort."
+- **S1.Q4:** "Which email address(es) should triage cover? *Why I'm asking:* If multiple, I'll set up per-address taxonomies."
+- **S1.Q5:** "Run frequency: once daily / 2x daily / 3x daily / on-demand only? *Why I'm asking:* Drives the default search window in triage (9h overlap for 2x/day)."
+- **S1.Q6:** "Anyone helping manage email — assistant, VA, team — or solo? *Why I'm asking:* Persona handling differs for delegated inboxes."
+
+**Action:** Build mental model. Do NOT write files yet. Note whether opportunity emails are a category (drives S4 skip-logic).
+
+## Section 2: Email Categories
+
+Propose 5–7 categories based on Section 1 — pre-recommend a subset, not the whole template menu:
+
+- New Opportunities
+- Active Conversations
+- Action Required
+- Financial
+- Important/Personal
+- Informational
+- Ignore/Low Priority
+
+Then three forcing questions, one at a time:
+
+- **S2.Q1:** "Here's my proposed taxonomy: [list]. Does this match your inbox reality — yes / mostly / no? *Why I'm asking:* If 'no', I need to redo the taxonomy before any other section makes sense."
+- **S2.Q2:** "Missing categories? List them. (Skip if none.) *Why I'm asking:* Missing categories produce uncategorized emails downstream, which hurts triage quality."
+- **S2.Q3:** "Which category takes the MOST time per email? *Why I'm asking:* That's where draft-reply effort needs to focus most."
+
+**Action:** Generate `email-taxonomy.md` with categories, signals (for each: trigger phrases / sender patterns / subject markers), and default actions per category.
+
+## Section 3: Reply Style & Voice
+
+Six grill-me questions plus the critical sample request:
+
+- **S3.Q1:** "Register: formal / casual / in-between? *Why I'm asking:* Calibrates default voice; we'll refine from samples next."
+- **S3.Q2:** "Three communication pet peeves — phrases you hate, openings you avoid. *Why I'm asking:* I treat these as forbidden tokens in drafts."
+- **S3.Q3:** "Phrases or sign-offs you always use — list as many as come to mind. *Why I'm asking:* These are your voice fingerprints."
+- **S3.Q4:** "Different persona for different contexts — e.g., assistant replies as you? *Why I'm asking:* Persona context changes pronoun + signature handling."
+- **S3.Q5:** "Typical reply length — one-liner / short paragraph / longer? *Why I'm asking:* Length is the easiest voice signal to get wrong."
+- **S3.Q6:** "Hard rules — never X / always Y? (E.g., never emojis, always reply within 24h, never take calls without context.) *Why I'm asking:* Hard rules are enforced as non-negotiable in every draft."
+
+### S3.SAMPLES (the critical highest-quality input)
+
+> **Paste 3–5 real sent emails from your inbox.**
+>
+> *Why I'm asking:* Self-description of voice is unreliable. Real samples are the best signal — I'll analyze them for voice patterns that supplement everything above. Use `scripts/voice_sample_analyzer.py` to extract patterns deterministically.
+
+If user runs a business: also ask about media kits, rate sheets, standard pitches, repeated replies.
+
+**Action:** Generate `email-patterns.md` with tone description (with do/don't examples), persona rules, templates, signatures, hard rules. See [`references/voice_calibration.md`](references/voice_calibration.md) for the sample-extraction discipline.
+
+## Section 4: Evaluation Framework (Conditional)
+
+**Skip-logic:** only run this section if Section 1 surfaced opportunity emails as a meaningful inbox category. Otherwise jump straight to Section 5.
+
+Six grill-me questions, one at a time:
+
+- **S4.Q1:** "First thing you check when pitched something — give me your gut filter. *Why I'm asking:* That's the top of the decision tree."
+- **S4.Q2:** "Three instant deal-breakers — things that make you decline immediately. *Why I'm asking:* These become PASS-auto signals."
+- **S4.Q3:** "Three things that make you immediately interested. *Why I'm asking:* These become TAKE-IT signals."
+- **S4.Q4:** "Standard pricing / terms — or 'no fixed pricing' if you negotiate every time. *Why I'm asking:* If you have a rate card, I'll generate one; if not, I'll skip."
+- **S4.Q5:** "Negotiation posture: firm / flexible / depends on context? *Why I'm asking:* Drives draft tone on counter-offers."
+- **S4.Q6:** "VIP senders or organizations that always get engagement — list names or domains. *Why I'm asking:* VIP list bypasses normal PASS filters."
+
+**Action:** Generate `evaluation-framework.md` (decision tree + recommendation categories + VIP list) AND `rate-card.md` if pricing exists.
+
+## Section 5: Blocklist & Patterns
+
+Three grill-me questions, one at a time:
+
+- **S5.Q1:** "Senders or domains to always skip — list them. (Skip if none.) *Why I'm asking:* Auto-blocklist saves the most time per run."
+- **S5.Q2:** "Patterns in emails you always delete — e.g., 'unsubscribe' links from specific marketers, recruiter cold outreach, newsletters? *Why I'm asking:* Patterns let triage auto-skip variants without exact-match maintenance."
+- **S5.Q3:** "Specific companies / recruiters / newsletters wasting time — list any. *Why I'm asking:* These seed the blocklist; triage will add more as you override decisions."
+
+**Action:** Generate `blocklist.md` (auto-maintained by triage thereafter).
+
+## Section 6: Current State
+
+Three grill-me questions, one at a time:
+
+- **S6.Q1:** "Active threads you're tracking — list with one-line context each. (Skip if none.) *Why I'm asking:* These become tracker entries so triage knows existing context."
+- **S6.Q2:** "Overdue replies — anything you should have responded to but haven't? *Why I'm asking:* Triage flags these as priority every run until resolved."
+- **S6.Q3:** "Time-sensitive items with deadlines — list with dates. *Why I'm asking:* Tracker enforces deadlines and surfaces them as overdue at the right time."
+
+**Action:** Generate `tracker.md` with active follow-ups table, overdue section, resolved section (empty), update log (empty). Also create empty `triage-log/` directory.
+
+## Section 7: Report Preferences
+
+Three grill-me questions, one at a time:
+
+- **S7.Q1:** "Delivery format — pick one: email draft to self / file in workspace / chat summary only. *Why I'm asking:* The triage report goes here every run."
+- **S7.Q2:** "Detail level — pick one: 30-second scan / detailed breakdown / both (scan first, expand on request). *Why I'm asking:* Affects report length."
+- **S7.Q3:** "Anything always shown first — e.g., overdue payments, VIP messages? *Why I'm asking:* Custom 'top-of-report' rules surface what you care about above standard sections."
+
+**Action:** Save these preferences into `email-taxonomy.md` under a "Report Preferences" section.
+
+## Section 8: Confirmation & Handoff
+
+List every file created with one-sentence summary. Then:
+
+> Your triage system is ready. Run the **inbox-triage** skill to process your inbox. First runs need oversight — system learns from your edits and overrides.
+
+Remind: re-run this setup anytime business/pricing/priorities change.
+
+Run `scripts/kb_validator.py --workspace ${WORKSPACE}` to confirm the 7-file contract is satisfied before final handoff.
+
+## Privacy Boundary
+
+**Never persist passwords, full account numbers, SSNs, or other sensitive credentials in knowledge base files.** If the user volunteers such info during the interview, acknowledge it but don't store it; the relevant KB file gets `[stored separately by user]` in its place.
+
+## Re-Run Behavior
+
+Re-running on an existing setup:
+
+1. Detect `${WORKSPACE}/Email/`
+2. For each existing file, ask per-file: **replace / merge / skip**
+3. Walk only the sections whose files the user chose to update
+4. Skip sections whose files the user kept
+
+## Error Handling
+
+| Situation | Behavior |
+|---|---|
+| Workspace inaccessible | Stop. Tell user where files would go and ask for permission/path |
+| User refuses to share samples | Use self-description; flag in patterns file that calibration may need iteration |
+| User says "skip this" mid-interview | Honor it; flag the gap in the file as `[needs follow-up]` |
+| Sensitive info volunteered | Acknowledge but don't persist; note in file as `[stored separately by user]` |
+| Re-run on existing setup | Detect existing files; ask user per-file: replace, merge, skip |
+| User has no pricing / opportunities | Skip Section 4 entirely; don't create empty files |
+
+## Portability
+
+- **Claude Code CLI:** Native — writes markdown files directly to filesystem.
+- **Claude.ai web:** Works with project files / artifacts. Document the alternate path: generate files as artifacts, instruct user to save to their workspace, or use connected file system if available.
+
+## Tooling
+
+| Script | Role |
+|---|---|
+| `scripts/kb_validator.py` | Validates the 7-file KB output (required files present, conditional files only if their sections ran, headers + structure correct). |
+| `scripts/section_progress_tracker.py` | JSON-backed walk state at `~/.inbox_setup_sessions/<session>.json`. Tracks active section, answered questions, committed files. |
+| `scripts/voice_sample_analyzer.py` | Extracts voice patterns from pasted sent-email samples — opening phrases, sign-offs, length distribution, register markers. |
+
+## References
+
+- [`references/kb_file_contract.md`](references/kb_file_contract.md) — the canonical 7-file contract (write perspective; mirror lives in `inbox-triage/references/`)
+- [`references/grill_me_section_walk.md`](references/grill_me_section_walk.md) — 8-section discipline, skip-logic, commit-per-section
+- [`references/voice_calibration.md`](references/voice_calibration.md) — sample-based voice extraction theory + anti-patterns
+
+## Anti-Patterns To Reject
+
+- Generating all files at once instead of walking through sections
+- Asking all questions in one batch
+- Hardcoded provider references (Gmail-only thinking)
+- Persisting sensitive credentials in knowledge base
+- Skipping the "why this question matters" explanation
+- Skipping the sample-emails ask for voice (it's the highest-quality input)
+- Overwriting existing files without consent on re-run
+- Forcing creation of `rate-card.md` or `evaluation-framework.md` when they don't apply
+
+---
+
+**Version:** 1.0.0
+**Source spec:** [`megaprompts/06-inbox-setup-megaprompt.md`](../../../../megaprompts/06-inbox-setup-megaprompt.md)
+**Build pattern:** Path B (direct conversion). Paired with `inbox-triage`.