About

Imported from xcrft/mastermind (skills/workflow/mastermind-architecture-review/SKILL.md). Install upstream with npx skills add xcrft/mastermind --skill mastermind-architecture-review. Copyright stays with the author.

Mastermind Architecture Review

Name: mastermind-architecture-review
Author: xcrft

Review whether a design preserves the system's runtime invariants. Do not turn the review into a generic architecture checklist or redesign the system merely because another style is possible.

Boundaries

[[mastermind-project-map]] supplies bounded structural navigation; it does not prove a request, event, or write reaches production code at runtime.
[[mastermind-change-impact]] supplies syntactic blast-radius evidence; it does not prove semantic compatibility.
[[mastermind-critical-review]] is the general proposal rubric. Use this skill when the decision specifically crosses runtime, state, retry, or evolution boundaries.

This is a read-only review. It may require a design change, but it does not implement one.

Inputs

Decision — the architecture or change being reviewed.
Scope — affected components, interfaces, state, and deployment boundary.
Evidence — codegraph results, entry points, handlers, schemas, storage code, tests, configs, deployment facts, or an explicit evidence gap.
Baseline — current contract or behavior when compatibility is relevant.

Never replace missing evidence with a familiar architecture pattern.

Review workflow

State the decision and the system invariant it must preserve.
Gather the narrowest evidence that can prove the actual path: indexed structure first, then read the entry point, boundary adapter, domain logic, state owner, and externally visible contract. Treat dynamic dispatch, framework registration, queues, reflection, and infrastructure routing as runtime evidence gaps until verified directly.

Reconstruct the path as ordered hops:

trigger -> transport -> admission/auth -> domain operation -> state owner
        -> external side effect -> response/event

Omit hops that do not exist; never add conventional layers by assumption.

Load only the references implicated by the design:
- process, service, queue, trust, or serialization crossings: references/runtime-boundaries.md
- authoritative and derived state, caches, indexes, replicas, or dual writes: references/source-of-truth.md
- retries, webhooks, commands, jobs, payments, or at-least-once delivery: references/idempotency.md
- API, event, schema, config, CLI, persisted-data, or rolling-deploy changes: references/backward-compatibility.md
For each material risk, describe one concrete failure sequence. Name the invariant at risk, the evidence, and the boundary where it can fail.
Bind every required change to a verification method that would fail before the change: a contract test, integration test, concurrent retry test, replay test, migration rehearsal, or production observation.
Give a bounded verdict. Unknown runtime facts stay unknown.

Evidence rules

An import edge or directory boundary is discovery evidence, not a runtime call-path proof.
A cache, search index, replica, or materialized view is not authoritative merely because the reviewed handler reads it.
An HTTP method, idempotency key field, or queue deduplication setting does not prove idempotency without operation scope, durable ownership, and atomicity.
An additive schema diff is not automatically compatible; old readers, stored messages, defaults, enum handling, and rollout order still matter.
If evidence cannot distinguish safe from unsafe, use insufficient evidence and name the exact file, contract, or runtime observation needed.

Severity and verdict

P0 — credible data loss, security breach, or duplicate money movement.
P1 — broken runtime path, split authority, duplicate side effect, or incompatible deployed contract.
P2 — missing proof, unsafe rollout assumption, weak recovery, or an untested boundary.
P3 — clarity or maintainability issue without a demonstrated contract risk.

Verdict is exactly one of: sound, sound with constraints, revise, or insufficient evidence.

Output contract

## Architecture review

**Verdict:** sound | sound with constraints | revise | insufficient evidence
**Decision:** <one sentence>
**Invariant:** <what must remain true>
**Evidence scope:** <files, contracts, runtime observations, and gaps>

### Runtime path
| Hop | Boundary/owner | Evidence | Contract or unknown |
|---|---|---|---|

### Findings
| Severity | Invariant at risk | Evidence | Failure sequence | Required change |
|---|---|---|---|---|

### Verification
| Risk | Proof required |
|---|---|

### Unknowns
- <only decision-changing missing evidence>

### Epistemic envelope
- **Observed:** <direct source, graph, test, or runtime evidence>
- **Inferred:** <bounded conclusion and reasoning>
- **Confidence:** high | medium | low — <reason>
- **Would change this conclusion:** <specific falsifier or superseding evidence>

Use at most seven findings. Do not emit generic advice, a technology shopping list, or speculative scalability work unrelated to the decision.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/xcrft-mastermind-mastermind-architecture-review/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

xcrft-mastermind-mastermind-architecture-review.ocm.jsonjson

{
  "ocm": "1",
  "id": "xcrft-mastermind-mastermind-architecture-review",
  "kind": "skill",
  "name": "mastermind-architecture-review",
  "description": "Review a proposed or existing architecture against the real runtime path, source-of-truth ownership, retry and idempotency behavior, and backward-compatibility constraints. Use for service boundaries, async workflows, persistence changes, external integrations, migrations, public APIs, events, schemas, or designs whose component diagram looks plausible but runtime safety is not yet proven.",
  "publisher": "xcrft",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "workflow",
      "architecture",
      "review",
      "reliability",
      "contracts",
      "github"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Review a proposed or existing architecture against the real runtime path, source-of-truth ownership, retry and idempotency behavior, and backward-compatibility constraints. Use for service boundaries, async workflows, persistence changes, external integrations, migrations, public APIs, events, schemas, or designs whose component diagram looks plausible but runtime safety is not yet proven."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github",
      "repository": "https://github.com/xcrft/mastermind",
      "path": "skills/workflow/mastermind-architecture-review/SKILL.md",
      "ref": "8f3d5e12e9e20723f78daf8db242e5fa47c98522",
      "url": "https://github.com/xcrft/mastermind/blob/8f3d5e12e9e20723f78daf8db242e5fa47c98522/skills/workflow/mastermind-architecture-review/SKILL.md",
      "key": "xcrft/mastermind/skills/workflow/mastermind-architecture-review/SKILL.md"
    }
  },
  "instructions": "# Mastermind Architecture Review\n\nReview whether a design preserves the system's runtime invariants. Do not turn\nthe review into a generic architecture checklist or redesign the system merely\nbecause another style is possible.\n\n## Boundaries\n\n- [[mastermind-project-map]] supplies bounded structural navigation; it does\n  not prove a request, event, or write reaches production code at runtime.\n- [[mastermind-change-impact]] supplies syntactic blast-radius evidence; it\n  does not prove semantic compatibility.\n- [[mastermind-critical-review]] is the general proposal rubric. Use this skill\n  when t",
  "cost": {
    "context_tokens": 1300
  }
}

Fetch it by URL: GET /api/v1/registry/xcrft-mastermind-mastermind-architecture-review/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.