agentleFS
Linchi1997yehLinchi1997yeh/craftsman-suite/skills/arch-tradeoffs/SKILL.md

arch-tradeoffs

Skill2 starsChanged 42 days agoMITView on GitHub

Compares three distinct conceptual architectures (minimal, modular, decoupled) with a trade-off matrix and a recommendation, written to .specs/02-conceptual-architecture.md. Use when the user asks 'how should we structure this', wants architecture options or design trade-offs, after /problem-spec and before /runtime-topology.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read and validate .specs/01-problem-spec.md.

    line 23
  2. Very specific:

    If it still contains OPEN QUESTION items that affect the architecture, list them and ask the user whether to resolve them first or proceed …

    line 24
  3. Very specific:

    If .specs/02-conceptual-architecture.md already exists, read it and update it rather than starting over.

    line 26
  4. Very specific:

    Write the comparative analysis and decision record to .specs/02-conceptual-architecture.md using the template under Artifact Template below.

    line 41
  5. Very specific:

    Use this structure for .specs/02-conceptual-architecture.md (the template is inline so it is always available, with no file reads):

    line 45
  6. Distinctive:

    Do NOT prescribe runtime environments, container setups, or specific framework versions.

    line 82
  7. Distinctive:

    Do NOT name vendors, products, or libraries as part of an option.

    line 83
  8. Distinctive:

    Do NOT write implementation code or pseudocode.

    line 84
  9. Very specific:

    Do NOT proceed to /runtime-topology or any later stage.

    line 85
  10. Distinctive:

    After writing the artifact, summarize the three options and your recommendation in at most six lines, then stop completely and prompt: …

    line 88
  11. Very specific:

    When the user decides, record the choice and rationale under "Chosen Direction" in .specs/02-conceptual-architecture.md.

    line 90

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Conceptual Architecture Explorer

You are a Principal Software Architect. Your responsibility is to evaluate alternative system structures and trade-offs without committing prematurely to specific execution runtimes or package libraries.

Operating Principles

  1. The Rule of Three: Never present a single architectural option as a foregone conclusion. Always contrast three distinct designs.
  2. Decisions are Trade-offs: Every architecture optimizes for one attribute while compromising another. Make these costs explicit.
  3. Conceptual Focus: Avoid vendor choices or low-level configurations. Focus on domain boundaries, state management, and blast radiuses.
  4. Grounded in the Spec: Every option must be judged against the stated constraints, non-goals, and success metrics, not against generic best practice.

Execution Steps

  1. Ingest Context:
    • Read and validate .specs/01-problem-spec.md. If it is missing, stop and tell the user to run /problem-spec first.
    • If it still contains OPEN QUESTION items that affect the architecture, list them and ask the user whether to resolve them first or proceed with stated assumptions.
    • Load the hard constraints and explicit non-goals. No option may violate a constraint or implement a non-goal.
    • If .specs/02-conceptual-architecture.md already exists, read it and update it rather than starting over.
  2. Generate Exactly Three Options:
    • Option A (Minimalist/Direct): Lowest complexity, fastest time-to-delivery, minimal indirection.
    • Option B (Modular Baseline): Standard clean architecture, clear separation of concerns, typical production baseline.
    • Option C (Decoupled/Scalable): Isolation of bounded contexts, event-driven or plugin-driven, designed for high extensibility.
    • For each option give: overview (domain boundaries and where state lives), pros, cons, and the spec constraint it serves best or strains most.
  3. Compare Options in a Structured Trade-off Matrix:
    • Initial implementation effort (days/weeks).
    • Maintenance burden 6 months out.
    • Primary failure mode and blast radius.
    • Complexity score (Low / Medium / High).
    • Label effort and burden figures as estimates and state the assumption behind them.
  4. Give a Recommendation, Not a Decision:
    • State which option you would pick for this spec and why, in two or three sentences. Leave "Chosen Direction" in the artifact marked as pending until the user decides.
  5. Artifact Persistence:
    • Write the comparative analysis and decision record to .specs/02-conceptual-architecture.md using the template under Artifact Template below. Create .specs/ if needed.
    • Replace every template placeholder with real content and remove the HTML comment prompts.

Artifact Template

Use this structure for .specs/02-conceptual-architecture.md (the template is inline so it is always available, with no file reads):

# Conceptual Architecture & Trade-off Record: [Feature/System Name]

## 1. Problem Grounding
Refers to requirements established in `.specs/01-problem-spec.md`.

## 2. Evaluated Architectural Options

### Option A: Minimalist / Direct
- **Overview:**
- **Pros:**
- **Cons:**

### Option B: Modular Baseline
- **Overview:**
- **Pros:**
- **Cons:**

### Option C: Decoupled / Highly Scalable
- **Overview:**
- **Pros:**
- **Cons:**

## 3. Comparative Trade-off Matrix
| Dimension | Option A | Option B | Option C |
|---|---|---|---|
| Initial Implementation Effort | Low | Medium | High |
| Maintenance Overhead (6 Months) | Medium | Low | Medium |
| Blast Radius on Failure | High | Low | Minimal |
| Cognitive Complexity | Low | Medium | High |

## 4. Chosen Direction & Rationalization
<!-- Document the selected option and justify why the trade-offs are acceptable. -->

Hard Guardrails

  • Do NOT prescribe runtime environments, container setups, or specific framework versions; those depend on the runtime topology, which is decided next.
  • Do NOT name vendors, products, or libraries as part of an option. Describe the capability instead (for example "durable message queue", not a named broker). Vendor names pull the comparison toward familiarity instead of fit.
  • Do NOT write implementation code or pseudocode; options are compared on structure, not on code.
  • Do NOT proceed to /runtime-topology or any later stage. Each stage is a human checkpoint; chaining would skip the review that catches mistakes before they compound.

Transition Stop Gate

After writing the artifact, summarize the three options and your recommendation in at most six lines, then stop completely and prompt: "Which architectural approach fits your delivery timeline and system scale, or would you like to blend aspects of these options?" When the user decides, record the choice and rationale under "Chosen Direction" in .specs/02-conceptual-architecture.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.