**First — extract repeat flags:** Follow the REPEAT PREAMBLE from `mastermind-repeat/SKILL.md`. Extracts `--repeat`, `--tillend`, `--maxruns`, `--wait`, `--rep`, `--loop` from `$ARGUMENTS` before all other parsing. If `is_continuation = true`, skip the empty-arguments check below. If `$ARGUMENTS` is empty, output this and STOP: > **Usage:** `/mastermind:improve ` > > Examples: > - `/mastermind:improve the authentication flow` > - `/mastermind:improve error handling across the codebase` > - `/mastermind:improve CLI startup performance` > - `/mastermind:improve the MCP server architecture` > > By default, analysis is saved to `docs/improvements/YYYY-MM-DD-.md`. Add `--monotask` to write to a monotask board instead. Do NOT proceed further if no arguments were provided. **Extract `--monotask` flag:** If present, set `USE_MONOTASK=true` and remove from `$ARGUMENTS`. Default: `USE_MONOTASK=false`. --- ## Step 0: Check monotask CLI *(skip unless `--monotask` was passed)* **Only run this step if `USE_MONOTASK=true`.** ```bash command -v monotask || (command -v cargo && cargo install monotask) ``` If neither exists, tell user to install Rust + monotask and STOP. --- ## Step 1: Gather Project Context Collect ALL of the following in parallel (skip any that error): 1. **Repo name**: Run `git remote get-url origin`, extract the last path segment, strip `.git`. Fallback: `basename` of the current working directory. Store as `REPO_NAME`. 2. **README**: Read `README.md` (first 200 lines). Skip if missing. 3. **Package manifest**: Read whichever exists first: `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`. Extract name, description, and keywords/tags. 4. **Knowledge graph**: Call `mcp__monomind__monograph_suggest` with the user's prompt (`$ARGUMENTS`). Skip if it errors or returns empty. 5. **Memory search**: Call `mcp__monomind__memory_pattern-search` with the user's prompt (`$ARGUMENTS`). Use the top 5 results. Bundle all gathered information into a single `PROJECT_CONTEXT` string for downstream agents. **DELEGATION RULE:** Every agent spawned in this command MUST include the `== AGENT DELEGATION CAPABILITY ==` block (from `mastermind/mastermind-delegation/SKILL.md`) in its prompt, immediately before `YOUR GOAL:`. This lets each agent spawn its own sub-agents when needed — delegation is recursive. --- ## Step 2: Deep Component Analysis This is what differentiates `/mastermind:improve` from `/mastermind:ideate`. Before generating improvement ideas, we must deeply understand the current state of the target component. Spawn 2 agents in parallel via the Agent tool: ### Agent 1: `feature-dev:code-explorer` Provide it with `$ARGUMENTS` and `PROJECT_CONTEXT`. It must: 1. **Trace the component** — find all files, functions, classes, and modules related to the target. Use `mcp__monomind__monograph_query` for each key term found. 2. **Map dependencies** — what does the component depend on? What depends on it? Use `mcp__monomind__monograph_shortest_path` for key relationships. 3. **Identify pain points** — look for: - Code smells (large files, deep nesting, god objects, duplicated logic) - Missing tests or low coverage areas - Performance bottlenecks (synchronous I/O, N+1 patterns, unnecessary allocations) - Security gaps (unvalidated inputs, missing auth checks, exposed secrets) - API inconsistencies (naming, error shapes, response formats) - Outdated patterns (callbacks vs async/await, old library versions) - Missing error handling or silent failures 4. **Measure complexity** — count files, lines, dependencies, and circular references. Return a structured analysis: ```json { "component": "name", "files": ["list of files touched"], "total_lines": N, "dependency_count": N, "pain_points": [ { "type": "code-smell|perf|security|api|testing|pattern", "description": "...", "file": "path", "severity": "critical|high|medium|low" } ], "strengths": ["things that are already well done"], "architecture_notes": "how it fits into the larger system" } ``` ### Agent 2: `researcher` (with WebSearch) Provide it with `$ARGUMENTS` and `PROJECT_CONTEXT`. It must: 1. **Search for best practices** related to the component's domain (e.g., "authentication best practices 2025", "CLI performance optimization techniques"). 2. **Find competitor/prior art** — how do similar tools/libraries solve this? 3. **Search for common improvements** — what do blog posts, conference talks, and docs recommend? 4. **Identify emerging patterns** — new libraries, frameworks, or techniques relevant to this area. Return structured research: ```json { "best_practices": [ { "title": "...", "description": "...", "source": "url or reference" } ], "prior_art": [ { "project": "name", "approach": "how they solve it", "takeaway": "what we can learn" } ], "emerging_patterns": [ { "pattern": "name", "description": "...", "relevance": "why it matters for us" } ] } ``` After both agents complete, merge their outputs into `COMPONENT_ANALYSIS`. --- ## Step 3: Setup Storage **File mode (default):** ```bash DATE=$(date +%Y-%m-%d) SLUG=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/-\+/-/g; s/^-//; s/-$//' | cut -c1-40) IMPROVE_FILE="docs/improvements/${DATE}-${SLUG}.md" mkdir -p docs/improvements ``` Write the file header using the Write tool: ```markdown --- source: mastermind:improve repo: created: component: <$ARGUMENTS> --- # Improvements: <$ARGUMENTS> ``` Store `IMPROVE_FILE`. --- **Monotask mode:** - Find or create space `$REPO_NAME` → store `SPACE_ID` - Find or create `monomind-improve` board with columns: `Discovered`, `Evaluated`, `Approved`, `Tasked`, `Deferred`, `Rejected` → store `BOARD_ID` and all column IDs --- ## Step 4: Generate Improvement Ideas Spawn a single `Software Architect` agent via the Agent tool. Provide it with: - The user's prompt: `$ARGUMENTS` - The full `COMPONENT_ANALYSIS` from Step 2 - The `PROJECT_CONTEXT` from Step 1 The agent must synthesize the code analysis and online research into concrete improvement ideas. For each idea, produce: ```json { "title": "Short, action-oriented title", "description": "2-3 sentences: what the improvement is, what problem it solves, and the expected benefit.", "category": "performance | security | reliability | maintainability | dx | testing | architecture", "evidence": "What from the analysis or research supports this (pain point ref, best practice ref, or prior art ref)", "estimated_impact": "Concrete expected outcome (e.g., '50% faster CLI startup', 'eliminate 3 code smells', 'cover 5 untested edge cases')" } ``` **Idea generation rules:** - Ideas must be grounded in the analysis — no generic "add more tests" without pointing to specific gaps - Each idea must reference either a pain point from the code analysis or a best practice from the research - Prefer high-impact, low-effort ideas first - Include at least one idea from each applicable category (perf, security, testing, etc.) - No duplicates — each idea must address a distinct improvement Persist each improvement: **File mode:** Append to `IMPROVE_FILE` using the improvement section format from `mastermind-taskfile/SKILL.md`: ```markdown ### > status: discovered > category: **Evidence:** **Estimated impact:** --- ``` **Monotask mode:** ```bash monotask card create $BOARD_ID $COL_DISCOVERED "