@xcraftmind/mastermind 0.24.0 → 0.26.0

package/share/skills/doc-stub-sync/scripts/doc_update.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+"""
+Sync local documentation stubs with their current online versions.
+
+See ../SKILL.md for the workflow this script implements.
+Run with --help for CLI usage.
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import hashlib
+import json
+import os
+import re
+import sys
+import tempfile
+import time
+from collections import defaultdict
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+import requests
+from bs4 import BeautifulSoup
+
+DEFAULT_STUB_PATTERN = r"Fetch live documentation:\s*(https?://\S+)"
+DEFAULT_TIMEOUT_SECONDS = 15
+DEFAULT_RATE_LIMIT_SECONDS = 1.0
+USER_AGENT = "mastermind-doc-stub-sync/0.1 (+https://github.com/aglumova/mastermind)"
+
+
+@dataclasses.dataclass
+class StubFile:
+    path: Path
+    url: str
+
+
+@dataclasses.dataclass
+class UpdateResult:
+    path: str
+    url: str
+    status: str  # "updated" | "current" | "unreachable" | "error"
+    old_hash: Optional[str] = None
+    new_hash: Optional[str] = None
+    delta_bytes: int = 0
+    reason: Optional[str] = None
+
+
+def find_stubs(root: Path, pattern: re.Pattern) -> list[StubFile]:
+    stubs: list[StubFile] = []
+    for path in root.rglob("*.md"):
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, PermissionError):
+            continue
+        match = pattern.search(text)
+        if match:
+            stubs.append(StubFile(path=path, url=match.group(1).strip()))
+    return stubs
+
+
+def normalize_text(text: str) -> str:
+    """Strip line-end whitespace and collapse blank runs for stable hashing."""
+    lines = [line.rstrip() for line in text.splitlines()]
+    out: list[str] = []
+    prev_blank = False
+    for line in lines:
+        if not line:
+            if not prev_blank:
+                out.append("")
+            prev_blank = True
+        else:
+            out.append(line)
+            prev_blank = False
+    return "\n".join(out).strip() + "\n"
+
+
+def content_hash(text: str) -> str:
+    return hashlib.sha256(normalize_text(text).encode("utf-8")).hexdigest()
+
+
+def local_body(text: str, pattern: re.Pattern) -> str:
+    """The local file's body, with the stub line removed for fair comparison."""
+    return pattern.sub("", text).strip()
+
+
+def extract_main(html: str) -> tuple[str, str]:
+    """Return (title, main-text) extracted from the upstream HTML."""
+    soup = BeautifulSoup(html, "html.parser")
+    for tag in soup(["script", "style", "noscript", "iframe", "nav", "footer"]):
+        tag.decompose()
+    main = soup.find("main") or soup.find("article") or soup.find("body") or soup
+    text = main.get_text(separator="\n")
+    title_tag = soup.find("title")
+    title = (
+        title_tag.get_text().split("|")[0].strip()
+        if title_tag
+        else urlparse(soup.find("link", rel="canonical").get("href", ""))
+        .path.rstrip("/")
+        .rsplit("/", 1)[-1]
+        if soup.find("link", rel="canonical")
+        else ""
+    )
+    return title, text
+
+
+def fetch(url: str, timeout: float) -> requests.Response:
+    return requests.get(url, timeout=timeout, headers={"User-Agent": USER_AGENT})
+
+
+def fetch_with_retry(url: str, timeout: float) -> requests.Response:
+    try:
+        return fetch(url, timeout)
+    except requests.exceptions.RequestException:
+        time.sleep(2)
+        return fetch(url, timeout)
+
+
+def build_updated_content(title: str, body_text: str, url: str) -> str:
+    header = f"# {title}\n\n" if title else ""
+    return f"{header}{body_text.strip()}\n\n---\n\nFetch live documentation: {url}\n"
+
+
+def write_atomic(path: Path, content: str) -> None:
+    tmp_fd, tmp_path = tempfile.mkstemp(dir=path.parent, prefix=".tmp-", suffix=".md")
+    try:
+        with os.fdopen(tmp_fd, "w", encoding="utf-8") as f:
+            f.write(content)
+        os.replace(tmp_path, path)
+    except Exception:
+        if os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        raise
+
+
+def process_stub(
+    stub: StubFile,
+    pattern: re.Pattern,
+    timeout: float,
+    dry_run: bool,
+) -> UpdateResult:
+    try:
+        response = fetch_with_retry(stub.url, timeout)
+    except requests.exceptions.RequestException as exc:
+        return UpdateResult(
+            path=str(stub.path),
+            url=stub.url,
+            status="unreachable",
+            reason=f"request failed: {exc}",
+        )
+
+    if response.status_code >= 400:
+        return UpdateResult(
+            path=str(stub.path),
+            url=stub.url,
+            status="unreachable",
+            reason=f"{response.status_code} {response.reason}",
+        )
+
+    title, upstream_text = extract_main(response.text)
+    new_content = build_updated_content(title, upstream_text, stub.url)
+    new_hash = content_hash(new_content)
+
+    try:
+        old_text = stub.path.read_text(encoding="utf-8")
+    except Exception as exc:
+        return UpdateResult(
+            path=str(stub.path), url=stub.url, status="error", reason=str(exc)
+        )
+
+    old_hash = content_hash(local_body(old_text, pattern))
+    cmp_hash = content_hash(local_body(new_content, pattern))
+
+    if old_hash == cmp_hash:
+        return UpdateResult(
+            path=str(stub.path),
+            url=stub.url,
+            status="current",
+            old_hash=old_hash,
+            new_hash=cmp_hash,
+        )
+
+    delta = len(new_content.encode("utf-8")) - len(old_text.encode("utf-8"))
+    if not dry_run:
+        try:
+            write_atomic(stub.path, new_content)
+        except Exception as exc:
+            return UpdateResult(
+                path=str(stub.path), url=stub.url, status="error", reason=str(exc)
+            )
+    return UpdateResult(
+        path=str(stub.path),
+        url=stub.url,
+        status="updated",
+        old_hash=old_hash,
+        new_hash=cmp_hash,
+        delta_bytes=delta,
+    )
+
+
+def run(
+    root: Path,
+    stub_pattern: str,
+    rate_limit_seconds: float,
+    timeout_seconds: float,
+    dry_run: bool,
+) -> dict:
+    pattern = re.compile(stub_pattern)
+    stubs = find_stubs(root, pattern)
+    if not stubs:
+        return {
+            "summary": {"scanned": 0, "updated": 0, "skipped_current": 0, "unreachable": 0, "errors": 0, "duration_seconds": 0},
+            "updated": [],
+            "unreachable": [],
+            "errors": [],
+        }
+
+    started = time.monotonic()
+    last_request_per_host: dict[str, float] = defaultdict(float)
+    results: list[UpdateResult] = []
+
+    for stub in stubs:
+        host = urlparse(stub.url).netloc
+        wait = (last_request_per_host[host] + rate_limit_seconds) - time.monotonic()
+        if wait > 0:
+            time.sleep(wait)
+        last_request_per_host[host] = time.monotonic()
+        results.append(process_stub(stub, pattern, timeout_seconds, dry_run))
+
+    summary = {
+        "scanned": len(results),
+        "updated": sum(1 for r in results if r.status == "updated"),
+        "skipped_current": sum(1 for r in results if r.status == "current"),
+        "unreachable": sum(1 for r in results if r.status == "unreachable"),
+        "errors": sum(1 for r in results if r.status == "error"),
+        "duration_seconds": round(time.monotonic() - started, 1),
+        "dry_run": dry_run,
+    }
+    return {
+        "summary": summary,
+        "updated": [dataclasses.asdict(r) for r in results if r.status == "updated"],
+        "unreachable": [dataclasses.asdict(r) for r in results if r.status == "unreachable"],
+        "errors": [dataclasses.asdict(r) for r in results if r.status == "error"],
+    }
+
+
+def cli(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="Sync local doc stubs with online sources.")
+    parser.add_argument("target_dir", type=Path, help="Root directory containing stub markdown files.")
+    parser.add_argument("--stub-pattern", default=DEFAULT_STUB_PATTERN,
+                        help="Regex with one capture group for the URL. Default: %(default)r")
+    parser.add_argument("--rate-limit", type=float, default=DEFAULT_RATE_LIMIT_SECONDS,
+                        help="Minimum seconds between requests to the same host. Default: %(default)s")
+    parser.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT_SECONDS,
+                        help="Per-request timeout in seconds. Default: %(default)s")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="Detect changes but do not write files. Report what would change.")
+    parser.add_argument("--report-file", type=Path,
+                        help="If set, write the JSON report to this path.")
+    args = parser.parse_args(argv)
+
+    if not args.target_dir.is_dir():
+        print(f"error: target_dir is not a directory: {args.target_dir}", file=sys.stderr)
+        return 2
+
+    report = run(
+        root=args.target_dir,
+        stub_pattern=args.stub_pattern,
+        rate_limit_seconds=args.rate_limit,
+        timeout_seconds=args.timeout,
+        dry_run=args.dry_run,
+    )
+
+    output_json = json.dumps(report, indent=2)
+    print(output_json)
+    if args.report_file:
+        args.report_file.write_text(output_json + "\n", encoding="utf-8")
+
+    return 0 if report["summary"]["errors"] == 0 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(cli(sys.argv[1:]))

package/share/skills/doc-stub-sync/scripts/requirements.txt

@@ -0,0 +1,2 @@
+requests>=2.31
+beautifulsoup4>=4.12

package/share/skills/flaky-finder/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: flaky-finder
+description: Identify flaky tests by running the suite repeatedly and bisecting failures across runs. Use when the user says "find flaky tests", "this test is flaky", "tests pass locally but fail in CI", or sees intermittent test failures.
+metadata:
+  version: 0.1.0
+  authors:
+    - mastermind
+  tags:
+    - testing
+  model: sonnet
+---
+
+# Flaky Test Finder
+
+Finds tests that pass and fail non-deterministically. Runs the suite N times, records which tests changed outcome between runs, and ranks them by flake rate.
+
+## When to use
+
+- User reports "tests pass locally but fail in CI"
+- A test failed once and the user wants to confirm if it's flaky before retrying
+- User explicitly asks for a flake audit before a release
+- Do NOT use for finding *broken* tests — those fail consistently. Use a regular test run for that.
+
+## Prerequisites
+
+- A working `<test-command>` for the project (`pytest`, `go test ./...`, `npm test`, etc.)
+- Time — flake hunting is inherently slow (10-50 runs of the full suite)
+
+## Steps
+
+1. **Confirm the test command.** Read the project's CI config or `package.json` / `Makefile`. If unclear, ask.
+2. **Establish a baseline.** Run the suite once. If it fails, the failures aren't flakes — they're broken. Stop and report.
+3. **Decide N.** Default to 20 runs. For long suites (>5min), drop to 10. For fast suites (<30s), go to 50.
+4. **Run N times, recording each test's pass/fail per run.** Use the project's machine-readable output if available (`pytest --junitxml`, `go test -json`, `jest --json`).
+5. **Compute flake rate per test.** A test that passed 18/20 times and failed 2/20 has a flake rate of 10%.
+6. **Rank by flake rate descending.** Anything between 1% and 99% is suspicious; 0% and 100% are deterministic.
+7. **For the top 3 flakiest, read the test code.** Look for: shared state, time-based assertions, network calls, ordering assumptions, race conditions.
+8. **Report findings.**
+
+## Outputs
+
+```markdown
+## Flake report — N=<N> runs of <test-command>
+
+### Flaky tests (sorted by flake rate)
+| Test | Flake rate | Likely cause |
+|---|---|---|
+| `tests/limiter_test.go::TestConcurrentBucket` | 35% (7/20 failed) | Race on shared counter, no `t.Parallel()` synchronization |
+| `tests/api_test.py::test_response_time` | 15% (3/20 failed) | Time-based assertion `< 100ms` — fails under load |
+
+### Deterministic failures
+- `tests/foo_test.py::test_bar` — failed all 20 runs. Not a flake; this test is broken.
+
+### Deterministic passes
+- <count> tests passed all <N> runs.
+```
+
+## Examples
+
+**Input:** "Our CI is flaky, can you find the culprit?"
+
+**Output (abbreviated):**
+```markdown
+## Flake report — N=20 runs of `pytest tests/`
+
+### Flaky tests
+| Test | Flake rate | Likely cause |
+|---|---|---|
+| `test_websocket_reconnect` | 25% | Race between `await ws.connect()` and the heartbeat loop |
+| `test_cache_eviction` | 5% | Wall-clock assertion `time.time() - start < 1.0` |
+
+### Deterministic
+- 312 passed all 20 runs
+- 0 failed all 20 runs
+```

package/share/skills/mastermind-incident-response/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: mastermind-incident-response
+description: Parallel workflow for production incidents — triage, stop the bleeding, investigate root cause via mmcg + git + .mastermind/tasks/ history, write a blameless postmortem, feed lessons back into CONTEXT.md and (if applicable) into the main workflow's spec template or critic dimensions. Use when the user says "incident", "outage", "rollback", "что-то сломалось в проде", or pastes paging alerts / error logs.
+metadata:
+  version: 0.1.0
+  authors:
+    - mastermind
+  tags:
+    - workflow
+    - incident-response
+    - postmortem
+    - operations
+  model: opus
+---
+
+# Mastermind — Incident Response
+
+A **parallel workflow** for handling production breakage. Different from the main 13-step planning workflow ([`mastermind-task-planning`](../mastermind-task-planning/SKILL.md)) which builds new things — this one **stops bleeding**, finds root cause, and turns lessons into systemic improvements.
+
+## When to Activate
+
+User says or pastes:
+- "incident", "outage", "production is down", "что-то сломалось в проде", "rollback"
+- Paging alerts (Datadog, PagerDuty, Sentry)
+- Error logs with stack traces
+- "users are reporting…"
+- "deploy broke something"
+
+## What this is NOT
+
+- **Not** the bug-triage flow for development-time bugs — those go through the regular planning workflow
+- **Not** a feature-request channel
+- **Not** a debugging session for the user's local environment
+- **Not** a substitute for paging an actual on-call engineer for sev0/sev1 incidents — the workflow assists, doesn't replace the human
+
+## Different Priorities Than Planning
+
+| Planning workflow | Incident response |
+|---|---|
+| Optimize for quality | Optimize for **time** |
+| 7-dim critic before doing anything | Bias toward **rollback first**, understand later |
+| Mandatory specs, alternatives, tests | Hot-fix is OK if rollback impossible |
+| "Did we design this right?" | "What's the fastest way to stop the bleeding?" |
+| Blameless review post-fact | Blameless reasoning **during** |
+
+You are in **operations mode**. Speed of bleed-stop > completeness of fix > root-cause depth > paperwork. Reverse that order during postmortem.
+
+## Phases
+
+### Phase 1 — Triage (target: first 5 minutes)
+
+Ask the user (or extract from pasted alert):
+
+1. **Symptom** — what users / monitoring see (one sentence, observable)
+2. **Scope** — how many users / how much traffic / which surfaces
+3. **Severity** — pick a number:
+   - **sev0** — total outage, paging fire
+   - **sev1** — major degradation, immediate action needed
+   - **sev2** — partial degradation, action within hours
+   - **sev3** — minor / cosmetic, action within days
+4. **Timeline** — when did this start? (correlate with deploys / changes)
+5. **What's been tried already**
+
+While asking, parallel-research with `mastermind-researcher` subagent:
+```
+git log --since='2 hours ago' --oneline    → what changed recently
+git log -10 --oneline                       → most recent commits
+ls -lt .mastermind/tasks/ | head -10                  → most recent specs
+mmcg_status                                → index health
+```
+
+Use see [`references/triage-checklist.md`](references/triage-checklist.md) for the full first-response checklist.
+
+### Phase 2 — Stop the bleeding (target: next 10 minutes after triage)
+
+**Order of preference:**
+1. **Rollback** to last known good — if you can identify it, do it
+2. **Disable the feature** — if feature-flagged, flip the flag off
+3. **Hot patch** — only if 1 and 2 not possible; this carries risk
+4. **Escalate** — if stuck > 10 min on Phase 2, page additional help / wake on-call
+
+For each option, write to user what you're about to propose. **Do not execute destructive ops** (`git push --force`, deploys) without explicit user confirmation per turn — they're operating the controls, you're advising.
+
+Mitigation tactics by failure type:
+- **Recent deploy broke things** → revert the deploy
+- **Recent config change broke things** → revert config
+- **Data corruption** → freeze writes, restore from backup, investigate cause separately
+- **External dependency degraded** → enable degraded-mode fallback if present; otherwise wait + monitor
+- **Resource exhaustion (memory, disk, connections)** → kill / restart / scale; investigate cause separately
+
+### Phase 3 — Investigate (after symptoms stop)
+
+With pressure off, find **root cause** — not just the symptom. Five-whys discipline.
+
+**Investigation playbook** — see [`references/investigation-playbook.md`](references/investigation-playbook.md) for the full set of mmcg + git + log patterns. Quick summary:
+
+- **What changed recently?** `git log --since='<time of incident start - 1h>' -- <suspected paths>`
+- **What's the blast radius of the change?** `mmcg query impact <symbol> --depth 3`
+- **Were the relevant specs in `.mastermind/tasks/` going to catch this?** Read their Tests Plan + Observability Plan sections
+- **Did observability fire?** If yes, why didn't it page sooner? If no, why wasn't it instrumented?
+- **Is this a recurrence?** Grep `CONTEXT.md` for the symptom — known gotcha?
+
+If a fix is needed, **don't write it inline in this incident flow** — open a `.mastermind/tasks/<NNN>-<short-name>.md` spec via the main workflow. The fix goes through the normal critic/auditor gates. Incident response identifies the need; planner designs the response.
+
+### Phase 4 — Postmortem (within 24h of resolution)
+
+Use [`references/postmortem-template.md`](references/postmortem-template.md). Sections:
+
+- **Summary** (1-2 sentences — what happened, impact, resolution)
+- **Timeline** (UTC, minute-resolution where relevant)
+- **What went wrong** (root cause, contributing factors)
+- **What went well** (yes, name what worked — psychological safety + reinforces good patterns)
+- **Why detection took N minutes** (separate from why-it-happened — detection is its own failure mode)
+- **Why mitigation took N minutes** (rollback fast? unclear who could act? missing runbook?)
+- **Action items** (specific, owned, dated — each becomes a `.mastermind/tasks/` spec or a CONTEXT.md update)
+
+**Blameless framing** — write about systems, not people:
+- ❌ "Engineer X deployed without testing"
+- ✓ "The deploy pipeline allowed merging with failing tests because the test job was marked non-blocking three weeks ago"
+
+If a person made a judgment call that turned out wrong, frame it as: "given the information available at the time, the action was reasonable; the lesson is that information X needs to be more accessible / surfaced earlier."
+
+### Phase 5 — Feed forward
+
+Two destinations:
+
+**A. Project `CONTEXT.md`** (immediate):
+- **Known gotchas** entry for the failure pattern — concrete + scenario + reference to postmortem path
+- **Don't-touch list** entry if a code area has subtle constraints now known
+- **Decision log** entry if the postmortem changed an architectural decision
+
+**B. Action items as new `.mastermind/tasks/` specs** (within days):
+- Each action item becomes a spec
+- Specs go through normal workflow (planner → critic → executor → auditor)
+- Link back to postmortem in spec's Notes section
+
+**C. Workflow improvements** (if applicable):
+- Did the spec for the offending change include an Observability Plan? If no, that's evidence the planner skill should make it more mandatory.
+- Did the critic's 7 dimensions miss this category of issue? Propose an 8th dimension or sharpening an existing one.
+- Did the auditor pass when it shouldn't have? Add a new check.
+
+Workflow improvements go into the mastermind repo itself as a meta-improvement spec. **The workflow learns from its own failures.**
+
+## Roles & subagents
+
+Most of incident response is run by the planner (in this mode), with these spawns:
+
+- **`mastermind-researcher`** — for git/mmcg fact-gathering during Phase 1 and Phase 3
+- **`mastermind-critic`** — for the postmortem's "what went wrong" section if there's a design question (e.g., "was this design fundamentally flawed?"). Optional.
+- **`mastermind-auditor`** — NOT used in incident response (it's a post-flight checker, doesn't apply here)
+- **`mastermind-task-planning`** (in main mode) — for any follow-up specs that come out of the postmortem
+
+## References
+
+- [`references/triage-checklist.md`](references/triage-checklist.md) — first 5 minutes
+- [`references/investigation-playbook.md`](references/investigation-playbook.md) — mmcg + git + .mastermind/tasks/ patterns for finding root cause
+- [`references/postmortem-template.md`](references/postmortem-template.md) — blameless postmortem fill-in