Dist Check
Scannednpx machina-cli add skill Langerrr/distributed-architect/dist-check --openclaw/dist-check — Coding-Time Boundary Analysis
Analyze code changes for distributed system correctness issues. Runs a two-pass analysis: boundary correctness, then concurrency correctness (if topology indicates).
Arguments
$ARGUMENTSmay contain: a file/dir path,--staged, or--diff <range>
Step 1: Gather Changes
Based on $ARGUMENTS:
- If a file/dir path is given, read those files
- If
--staged, rungit diff --cached - If
--diff <range>, rungit diff <range> - If no arguments, run
git difffor uncommitted changes - If no diff at all, ask the user what change to analyze
Identify which components are being modified.
Step 2: Load Project Topology
Look for a topology file in the project (.dist-architect/topology.yaml, or check project CLAUDE.md for location). If none exists, note this and proceed with what you can infer from the code.
Step 3: Classify the Change
For each modified component, determine which boundary signal applies:
| Signal | Condition |
|---|---|
state-mutation | Changing state/status that another process reads |
data-lifecycle | Data crossing a serialization, network, or storage boundary |
failure-mode | Error handling for cross-component operations |
interaction | New message type, API call, or event between components |
If none apply (purely internal, single-component change), report "No boundary crossing detected" and stop.
Step 4: Pass 1 — Boundary Correctness
Read the relevant reasoning module from the plugin's modules/ directory and walk through its checklist. Answer each question concretely for the specific change. Do not skip questions.
Document:
- Each checklist question and your answer
- Any concerns found
- Any assumptions the change makes about other components
Step 5: Pass 2 — Concurrency Correctness
Check the topology: is the component being modified on the "1" side of a 1:N relationship?
- If yes: Read
modules/concurrency.mdfrom the plugin directory and walk through its checklist. - If no: Skip this pass. Note: "No concurrency concern at this boundary (1:1 or N-side)."
Step 6: Anti-Pattern Scan
Check if the change matches any known anti-pattern shapes. Read the catalog entries from the plugin's catalog/ directory:
- Tight retry loop (AP-1)
- Lost data at ACK (AP-2)
- Channel conflation (AP-3)
- Boundary state leak (AP-4)
- Compounding retry (AP-5)
- Premature state transition (AP-6)
Step 7: Output
Report findings in this format:
## Distributed Systems Analysis
**Components involved**: [list]
**Boundary type**: [state-mutation | data-lifecycle | failure-mode | interaction]
**Topology**: [cardinality at this boundary]
### Pass 1: Boundary Correctness
[Checklist results — concerns or "clean"]
### Pass 2: Concurrency
[Checklist results, or "skipped — no 1:N at this boundary"]
### Anti-Pattern Check
[Matches found, or "none"]
### Recommendations
[Specific changes needed, or "no issues found"]
### Topology Update
[Does the topology file need updating? If yes, what changed.]
Source
git clone https://github.com/Langerrr/distributed-architect/blob/main/skills/dist-check/SKILL.mdView on GitHub Overview
Dist Check analyzes code changes in distributed systems to surface correctness issues across component boundaries. It runs a two-pass analysis: boundary correctness first, then concurrency correctness if the topology indicates, helping you catch cross-component problems before committing.
How This Skill Works
Run with file/dir paths, --staged, or --diff <range>, or diff uncommitted changes by default. It identifies modified components, loads topology from the project (.dist-architect/topology.yaml) and classifies changes into boundary signals (state-mutation, data-lifecycle, failure-mode, interaction). Then Pass 1 evaluates boundary correctness via the plugin module checklist; if the topology indicates, Pass 2 checks concurrency on 1:N relationships; a final anti-pattern scan and a summarized report are produced.
When to Use It
- You are changing code that touches multiple components or interfaces across services and want to verify boundary correctness.
- Your change affects serialization, data crossing boundaries, or cross-component state transitions (data-lifecycle or state-mutation).
- You want to validate concurrency implications at a boundary when topology shows 1:N relationships.
- You need to surface potential anti-patterns (e.g., tight retry loops, boundary state leaks) before committing.
- Topology exists or is inferred and you want an automated cross-check before merging changes.
Quick Start
- Step 1: Decide the change scope (files/dirs, --staged, or --diff <range>).
- Step 2: Run dist-check with the chosen scope (e.g., dist-check <scope> or dist-check --staged).
- Step 3: Open the Distributed Systems Analysis report and fix issues; update topology if needed.
Best Practices
- Identify exactly which components are modified and map them to boundary signals (state-mutation, data-lifecycle, failure-mode, interaction).
- Always run Pass 1 (boundary correctness) before considering the concurrency check.
- If topology indicates a 1:N relationship, perform Pass 2 and review concurrency questions carefully.
- Run the anti-pattern catalog scan (AP-1 to AP-6) and address any matches with concrete fixes.
- Keep topology.yaml up to date and document any assumptions or deviations observed during analysis.
Example Use Cases
- Modifying a shared service that updates a distributed cache—Dist Check flags potential state-mutation and data-lifecycle issues across components.
- Introducing a new inter-service API call—Dist Check surfaces interaction signals and reviews boundary correctness.
- Changing serialization format between components—Dist Check highlights data-lifecycle boundaries and potential compatibility concerns.
- Adjusting error handling across cross-service calls—Dist Check looks for failure-mode handling and cross-component effects.
- Updating topology due to deployment changes—Dist Check uses topology to assess concurrency and boundary impacts.
