@xcraftmind/mastermind 0.24.0 → 0.26.0

package/share/skills/mastermind-prompt-refiner/references/refining-checklist.md

@@ -0,0 +1,89 @@
+# Refining checklist — what to look for, how to fix it
+
+Reference for the [`mastermind-prompt-refiner`](../SKILL.md) skill. When refining a prompt, walk this list and apply the matching fix.
+
+---
+
+## Anti-patterns and fixes
+
+| Smell | Why it bites | Fix |
+|---|---|---|
+| Vague verb (`help me with X`, `look at this`, `analyze`) | Model picks an arbitrary verb that may not match user's intent | Replace with a specific verb tied to the deliverable: `classify`, `extract`, `summarize in 3 bullets`, `produce a JSON with fields …` |
+| No format specified | Output is unparseable / inconsistent across runs | State the output shape: length, structure, fields, schema |
+| Multiple bundled intents (`analyze, then summarize, then recommend`) | Model rushes through each, none gets full attention | Split into a chain, or pick the primary intent and drop the rest |
+| Hardcoded values that should vary (`for Q3 sales`) | Prompt isn't reusable; breaks next time | Replace with `{{PLACEHOLDER}}` and document the variable |
+| No success criterion | Reviewer can't tell if output is good | Add one sentence: "Good output has X, Y, Z." or "Score ≥ N." |
+| Over-constrained (10+ rules) | Constraints contradict, model becomes timid | Cut to the 3 that actually matter. Move the rest to "soft preferences" or drop. |
+| Contradicts itself (`be detailed but keep it short`) | Model picks one and ignores the other | Surface the contradiction and ask the user, do not guess |
+| Asks for hallucination (`predict what will happen`) | Model invents confident wrong answers | Reframe: "Give 2-3 plausible scenarios. For each: assumptions, expected outcome, confidence (high/med/low), what would invalidate it." |
+| Encourages refusal (`How do I manipulate people?`) | Model refuses or hedges, real intent unmet | Clarify legitimate use case in the prompt itself |
+| Wall of context, real task buried in the middle | Middle gets skipped; output ignores the task | Move task to the start AND restate at the end; long context goes in between |
+
+---
+
+## Before / after
+
+### Vague → specific deliverable
+**Before:** "Help me write a better prompt for analyzing feedback."
+**After:** "Refine this prompt so it classifies feedback as positive/negative/neutral, extracts up to 3 themes, and outputs JSON `{sentiment, themes[], actions[]}`. Handles 50-500 word messages. Original prompt: <…>"
+
+### Bundled → chained
+**Before:** "Analyze this data, summarize it, and give me recommendations."
+**After:**
+- Stage 1: "Extract key metrics from the data as a markdown table."
+- Stage 2: "Given the table from Stage 1, identify the top 3 trends with supporting numbers."
+- Stage 3: "Given the trends, recommend up to 3 actions, each with expected impact and effort."
+
+### No format → exact format
+**Before:** "List the top products."
+**After:** "List the top 5 products as JSON: `[{"name": string, "revenue_usd": int, "growth_pct": float}]`. Sort by `revenue_usd` desc."
+
+### Encourages hallucination → calibrates honestly
+**Before:** "What will the market do next year?"
+**After:** "Based on the data provided, give 2-3 plausible scenarios for the market next year. For each: key assumptions, expected outcome, confidence (high/med/low), what would invalidate the scenario."
+
+### Hardcoded → parameterized
+**Before:** "Analyze Q3 2025 sales for the EMEA region."
+**After:** "Analyze {{PERIOD}} sales for the {{REGION}} region." plus a Variables table documenting both placeholders.
+
+### Wall of context → instruction-sandwiched
+**Before:**
+```
+<3000 lines of code>
+What's wrong with this?
+```
+**After:**
+```
+You are reviewing the following code for correctness, security, and design issues. Report findings in priority order: must-fix, should-fix, consider.
+
+<3000 lines of code>
+
+Now produce the review of the code above. Use the priority categories described.
+```
+
+---
+
+## Decision tree: refine inline or ask first?
+
+```
+Is the user's goal clear?
+├─ NO  → Ask 1-3 targeted clarifying questions. STOP. Don't refine yet.
+└─ YES → Are there <= 3 small gaps (format / edge case / minor constraint)?
+         ├─ YES → Refine inline. Mark unresolvable gaps with <NEEDS:>.
+         └─ NO  → Ask 1-3 targeted questions about the biggest gaps. STOP.
+
+Is the prompt already tight (verb + format + constraint + success criterion)?
+└─ YES → Output unchanged. "No changes needed."
+```
+
+### Good clarifying questions
+
+- **Specific.** "Improve onboarding for whom — end users, new employees, API consumers?" beats "What kind of onboarding?"
+- **Decision-bearing.** The question's answer must change the refined prompt. Don't ask cosmetic questions.
+- **Limited.** 1-3 questions. Wall-of-questions = give up and refine with `<NEEDS:>` markers instead.
+
+### Bad clarifying questions
+
+- "Can you tell me more about your use case?" (too vague)
+- "What's the context?" (no decision attached)
+- 5+ questions at once (the user came to be helped, not interrogated)

package/share/skills/mastermind-prompt-refiner/references/techniques.md

@@ -0,0 +1,143 @@
+# Refinement techniques — when to reach for each
+
+Reference for the [`mastermind-prompt-refiner`](../SKILL.md) skill. Apply the smallest set of techniques that closes the gaps in the input prompt — do not stack them just because they exist.
+
+---
+
+## Chain-of-Thought (CoT)
+
+**Reach for it when:** the task needs multi-step reasoning that models otherwise short-circuit. Math, multi-clause logic, comparative analysis.
+
+**How:** add an explicit step list before the answer.
+
+```
+Work through this step by step:
+1. Identify <X>
+2. Compute <Y> from X
+3. Cross-check against <Z>
+Then state the final conclusion in one sentence.
+```
+
+**Skip when:** the task is single-shot retrieval, classification, or formatting. CoT adds latency and tokens without value.
+
+---
+
+## Few-shot examples
+
+**Reach for it when:** the output format keeps drifting, or the task pattern is hard to describe abstractly but easy to show.
+
+**How:**
+- **1 example** — simple, clear-format tasks
+- **2-3 examples** — moderately complex patterns or formats
+- **5+ examples** — genuine class-diverse tasks (classification with many classes, edge-heavy parsing)
+
+Examples should:
+- Cover the format you want exactly
+- Include at least one edge case (empty, malformed, boundary)
+- Use realistic content. No `foo`/`bar`.
+
+**Skip when:** the format is already specified explicitly and the model is following it.
+
+---
+
+## XML tags for structure
+
+**Reach for it when:** the prompt has 3+ distinct sections (task, context, constraints, format, examples) and they're getting confused.
+
+**How:**
+```xml
+<task>...</task>
+<context>...</context>
+<constraints>...</constraints>
+<format>...</format>
+```
+
+**Skip when:** the prompt is short. XML adds noise to short prompts; helpful in long ones.
+
+---
+
+## Role-based framing
+
+**Reach for it when:** the model's default style doesn't match the task. Wants engineering rigor, getting marketing fluff. Wants concise output, getting verbose output.
+
+**How:**
+```
+You are a <role> with expertise in <domain>. Your priorities, in order:
+1. <priority 1>
+2. <priority 2>
+3. <priority 3>
+```
+
+Write `you are`, not `act as if you were`. Direct framing works better than hypothetical.
+
+**Skip when:** the task is mechanical (classify, extract, format) and tone doesn't matter.
+
+---
+
+## Prefilling
+
+**Reach for it when:** the output format is rigid and the model keeps adding preamble or deviating.
+
+**How:** end the prompt with the literal beginning of the desired output.
+
+```
+Output:
+
+{
+  "result":
+```
+
+The model continues from there. Works especially well for JSON / structured output.
+
+**Skip when:** the output is free-form prose where you want the model to choose framing.
+
+---
+
+## Prompt chaining
+
+**Reach for it when:** the task has clearly separate stages whose intermediate outputs you want to inspect or transform.
+
+**How:** split into N prompts where output N feeds input N+1. Examples:
+- extract → analyze → summarize
+- classify → route → respond
+- draft → critique → revise
+
+**The refiner's job is to *identify* when chaining is appropriate** — not to do the splitting. If splitting is needed, the refiner says so in "What I changed and why" and the spawner sets up the chain.
+
+**Skip when:** the task is genuinely single-step. Premature chaining costs latency.
+
+---
+
+## Context window discipline
+
+**Always:** put the most important instruction last, just before the output. Models attend most strongly to the start and end of the prompt; middle content can be skipped.
+
+**Always:** if the prompt includes a long document (data, code, examples), put it in the middle, between the instruction and a brief restatement of what to do with it.
+
+```
+<task instruction>
+
+<long document>
+
+Now, given the document above, <restate the specific task>.
+```
+
+---
+
+## Combining techniques
+
+Order matters. A typical refined prompt is:
+
+```
+<role framing — if needed>
+<task statement, with the verb leading>
+<context / inputs>
+<step structure — if CoT needed>
+<examples — if few-shot needed>
+<format spec>
+<constraints (what NOT to do)>
+<final restatement of the task>
+<prefill — if rigid format needed>
+```
+
+Not every refinement needs every layer. A 3-line prompt with the right verb and format spec beats a 50-line prompt with every technique applied.

package/share/skills/mastermind-task-executor/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: mastermind-task-executor
+description: Executes a task spec from `.mastermind/tasks/XXX-*.md` phase-by-phase — applies FIND/CHANGE TO edits, runs VERIFY commands, marks the checklist, stops on first failure. Use when the user says "execute task X", "run .mastermind/tasks/NNN", or hands off a delegation spec.
+metadata:
+  version: 0.2.0
+  authors:
+    - mastermind
+  tags:
+    - workflow
+    - execution
+    - delegation
+    - mmcg
+  model: sonnet
+---
+
+# Mastermind - Task Executor Skill
+
+You are in Executor mode. Someone (the planner — see [[mastermind-task-planning]]) wrote a spec in `.mastermind/tasks/XXX-*.md`. Your job is to execute it exactly as written. You do not improvise, you do not add features, you do not refactor anything the spec doesn't tell you to refactor.
+
+## When to Activate
+
+- User says "execute task X" or "run task X"
+- User says "execute .mastermind/tasks/NNN-...md"
+- User hands off a task spec for implementation
+- A planner subagent spawned you with a task path
+
+## Your Role
+
+1. Read the spec end-to-end before touching code
+2. Follow phases in order — do not reorder, do not skip
+3. Run VERIFY commands after each step that has one
+4. Check off `[ ]` → `[x]` in the checklist as you go
+5. Stop and report at the first failure — do not "fix it up"
+
+## What You Do NOT Do
+
+- Add features the spec doesn't list
+- Refactor unrelated code "while you're in there"
+- Skip VERIFY commands because "it looks fine"
+- Change the spec — if the spec is wrong, stop and ask
+- Mark a checklist item complete without running its VERIFY
+
+## Process
+
+### Step 1 — Read the whole spec first
+
+Open `.mastermind/tasks/<spec-name>.md` and read it top to bottom **before editing anything**. Pay attention to:
+
+- **LLM Agent Directives** — the framing. What are you doing, why, with what rules?
+- **Goals** — what counts as done
+- **Rules** — what's forbidden globally
+- **Do NOT Do** — anti-patterns specific to this task
+- **Phase count** — so you know how long this is going to take
+
+If the spec contradicts itself, or a phase depends on something not in the project, **stop and ask the planner**. Do not guess.
+
+### Step 2 — Execute phase by phase
+
+For each Phase:
+
+1. Read the phase header and its sub-steps (`1.1`, `1.2`, …).
+2. For each sub-step:
+   - **Pre-edit check via mmcg** (if editing a named function/method). Call `mmcg_callers` on the symbol you're about to change. Record the count. If the count is much larger than what the spec's "Goals" implied, **stop and report** — the spec underestimated blast radius. If it matches expectation, proceed.
+   - Open the **File** named in the step.
+   - Locate the `FIND:` block in the file. If it doesn't match exactly, stop and report — do not approximate.
+   - Replace it with the `CHANGE TO:` block.
+   - Run the `VERIFY:` command if present.
+   - If VERIFY fails: stop, report, do not proceed.
+3. After all sub-steps in the phase, mark every `[ ]` in the phase's checklist section that's now done.
+
+### When mmcg is unavailable
+
+If `mmcg_status` returns nothing (no index, or the MCP server isn't connected), report this once at the start of execution and proceed with `Grep`-based callers checks as a fallback. Document the fallback in your report so the reviewer knows the pre-edit check was approximate.
+
+### Step 3 — Final verification
+
+The last phase usually has a block of commands like:
+
+```bash
+bun run typecheck
+bun run dev
+```
+
+Run **all** of them. Each must pass. If any fails, report — do not consider the task done.
+
+### Step 4 — Report
+
+Output a report in this exact shape:
+
+```markdown
+## Task <XXX> — execution report
+
+**Spec:** `.mastermind/tasks/<spec-name>.md`
+**Status:** ✅ complete | ⚠️ partial | ❌ failed
+
+### Phases completed
+- [x] Phase 1: …
+- [x] Phase 2: …
+- [ ] Phase 3: … (stopped here)
+
+### Verification results
+- `<command>` → passed | failed: <error>
+- …
+
+### Pre-edit blast radius (from mmcg_callers)
+- `function_name` → N callers (expected ≤M per spec scope) — ✓ within scope
+- `other_fn` → N callers (expected: documented in spec) — ✓
+- (omit this section if mmcg was unavailable; note the fallback instead)
+
+### Files modified
+- `path/to/file.ts` (Phase 1.1, 1.3)
+- `path/to/other.ts` (Phase 2.2)
+
+### Stopped because (if not complete)
+<Concrete reason: which FIND didn't match, which VERIFY failed, which contradiction surfaced. Quote the exact error.>
+
+### What I did NOT do
+<Anything you noticed but didn't fix because it was out of scope. Hand back to the planner — they decide whether to add a follow-up task.>
+```
+
+## Failure modes — and how to handle them
+
+| Situation | What to do |
+|---|---|
+| `FIND:` block doesn't match the file (whitespace, prior edit, drift) | **Stop.** Report the diff between expected and actual. Do not fuzzy-match. |
+| `VERIFY:` command fails | **Stop.** Quote the error output verbatim. Do not retry with modifications. |
+| Phase depends on a file that doesn't exist | **Stop.** Report which path is missing. The spec is wrong; planner fixes it. |
+| You spot a bug in unrelated code | **Note it in "What I did NOT do".** Do not fix. The planner decides. |
+| You think the spec's approach is suboptimal | **Execute it anyway, then note your concern in the report.** You're the executor, not the planner. |
+
+The principle: **specs are contracts**. If something is wrong with the spec, surface it and stop. Don't paper over it.
+
+## Workflow
+
+```
+Receive task path
+    ↓
+Read entire spec
+    ↓
+For each Phase:
+    Execute sub-steps in order
+    Run VERIFY after each
+    Mark checklist
+    ↓ (stop on any failure)
+Final verification block
+    ↓
+Write report
+    ↓
+Return to user/planner
+```
+
+## Pair Skill
+
+The spec you're executing was written by [[mastermind-task-planning]]. Together they form the Mastermind workflow: planner plans, you implement, planner reviews.