xD4O/architecture-reasoning
skills/architecture-reasoning/SKILL.md
MANDATORY architecture analysis. You MUST invoke this skill before making module boundary decisions, build-vs-buy choices, technology selections, data model designs, API contracts, or any structural decision that is expensive to reverse. Do NOT propose architecture without running reversibility classification, boundary analysis, and bottleneck identification. Invoke BEFORE writing implementation plans for non-trivial systems.
$ install --global
skillsauthnpx skillsauth add xD4O/praxis architecture-reasoningInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 23, 2026, 6:25 PM341.6s1 file scanned
SKILL.md
- name:
- architecture-reasoning
- description:
- >
Architecture Reasoning Protocol
EXTREMELY_IMPORTANT: This is a MANDATORY protocol, not a suggestion. Follow every step. Do not skip steps. Do not combine steps. Do not summarize. Work through each gate in order.
You're making a structural decision. These are expensive to reverse. Reason carefully.
STEP 1 — Classify the decision's reversibility
Type 1 (one-way door): Database schema, public API contract, core data model, infrastructure provider, primary language/framework choice. → Requires full protocol below. Do not rush.
Type 2 (two-way door): Internal module boundaries, library choices, config format, naming conventions, internal API between your own services. → Run abbreviated protocol (Steps 2 and 5 only). Decide fast, iterate.
STEP 2 — Map what exists
Before designing anything new, understand what's already there.
- What components exist today?
- What are the current boundaries? (services, modules, packages)
- Where are the current pain points? (coupling, bottlenecks, tech debt)
- What constraints does the existing system impose on new design?
If this is greenfield (nothing exists), state that and skip to Step 3.
STEP 3 — Evaluate build vs buy vs adopt
For each major component in the design, ask:
| Question | If YES → | |---|---| | Does a well-maintained OSS/SaaS solution exist? | Evaluate adopting it | | Is this a commodity capability (auth, email, storage, logging)? | Buy/adopt, don't build | | Is this your core differentiator? | Build it — this is where your value lives | | Will you need to customize it beyond what exists? | Build if customization > 40% |
State each component's classification: BUILD / BUY / ADOPT.
STEP 4 — Boundary analysis
For every proposed module or service boundary, verify:
Cohesion test: "Can I describe this module's purpose in one sentence without 'and'?"
- YES → Boundary is well-placed.
- NO → Module does too many things. Split it.
Coupling test: "If I change module A's internals, does module B need to change?"
- NO → Good separation.
- YES → Missing abstraction at the boundary. Add an interface.
Data ownership test: "Does exactly one module own each piece of data?"
- YES → Clean ownership.
- NO → Shared mutable state. This is where bugs breed. Assign a single owner.
Communication test: "How do these modules talk?"
- Direct function calls → Fine for monolith. Tight coupling for services.
- Events/messages → Loose coupling. Good for independent deployment.
- Shared database → Almost always wrong. Each module owns its data.
STEP 5 — Spot the bottleneck
Apply Theory of Constraints: which single component limits the system's overall capacity? Everything else is irrelevant until that bottleneck is addressed.
- Where does data queue up?
- Which step is slowest?
- Which component fails first under load?
Name the bottleneck explicitly. Your architecture must address it.
Output format
ARCHITECTURE ANALYSIS
├── Decision type: [Type 1 / Type 2]
├── Components: [BUILD: x, y | BUY: z | ADOPT: w]
├── Boundaries: [cohesion ✓/✗ | coupling ✓/✗ | data ownership ✓/✗]
├── Bottleneck: [identified component and why]
├── Key risk: [the one thing most likely to require rework]
└── Confidence: [HIGH / MEDIUM / LOW]
Type 1 decisions with MEDIUM or LOW confidence require explicit human sign-off with the risks stated clearly. Do not bury risks in optimistic framing. </HARD-GATE>
Superpowers handoff
After architecture analysis is complete and user confirms:
If Superpowers is installed → invoke Skill(superpowers:brainstorming) if design
exploration is needed, or Skill(superpowers:writing-plans) if the architecture is
confirmed. Pass your build/buy/adopt classifications, boundary analysis, and bottleneck
identification as context. Do NOT write the implementation plan inside this skill.
PRAXIS architected. Superpowers plans and builds.
If Superpowers is NOT installed → proceed to implementation planning yourself using the architecture analysis as the foundation.
Related Skills
xD4O/using-praxis
development
VerifiedTrustedCommunity
MANDATORY — HIGHEST PRIORITY SKILL. You MUST invoke this skill (praxis) BEFORE invoking superpowers:brainstorming or ANY other skill when the task is non-trivial. This skill classifies the problem, selects reasoning frameworks, and runs threat analysis BEFORE brainstorming begins. Do NOT invoke superpowers:brainstorming first. Do NOT respond directly. Do NOT ask clarifying questions on your own. Invoke praxis FIRST, complete its gates, THEN hand off to superpowers:brainstorming. Non-trivial means: system design, feature planning, architecture decisions, debugging, security-sensitive code, trade-off evaluation, code review, or refactoring. Trivial means: fix a typo, rename a variable, answer a factual question, run a command.
9SKILL.mdUpdated Apr 23, 2026
xD4O/strategic-reasoning
development
VerifiedTrustedCommunity
MANDATORY strategic analysis. You MUST invoke this skill for business decisions, product strategy, competitive analysis, roadmap prioritization, or any decision about WHAT to build rather than HOW to build it. Do NOT skip SWOT analysis. Do NOT present strategy without measurable OKRs. Invoke when the problem is about direction, positioning, or priorities rather than implementation.
9SKILL.mdUpdated Apr 23, 2026
xD4O/security-reasoning
development
VerifiedTrustedCommunity
MANDATORY threat analysis. You MUST invoke this skill before writing or approving ANY code involving authentication, authorization, cryptography, input handling, payment processing, PII, secrets management, API endpoints, or trust boundaries. Do NOT write security-sensitive code without running STRIDE analysis first. Do NOT say you will add security later. Auth is a design decision, not a feature to bolt on.
9SKILL.mdUpdated Apr 23, 2026
xD4O/problem-classification
development
VerifiedTrustedCommunity
MANDATORY first step. You MUST invoke this skill before brainstorming, designing, or planning any non-trivial work. Do NOT start asking clarifying questions on your own — this skill's gates ARE the clarifying questions. Invoke when the user asks to build, design, plan, create, architect, or implement anything substantial. Do NOT skip this because the task seems straightforward. Straightforward-seeming tasks with wrong framing produce the most expensive failures.
9SKILL.mdUpdated Apr 23, 2026