exploring-system-design

exploring-system-design

An agent skill for architecture and system-design work: clarifying half-formed problems, exploring the design space without premature convergence, exposing assumptions and trade-offs, stress-testing candidate designs, and producing durable design documentation. Its terminal state is improved design understanding and durable artifacts — not an implementation plan.

Developed test-first per superpowers:writing-skills (RED → GREEN → REFACTOR): 10 pressure scenarios were run against a no-skill baseline, the skill was written against the documented failures, re-run, and loophole-fixed. All 10 scenarios pass the final skill.

Layout

.claude-plugin/plugin.json    # plugin manifest (name, version, keywords)
skills/exploring-system-design/
  SKILL.md                    # the skill (frontmatter + core process and rules)
  design-lenses.md            # drivers, boundary prompts, stress-test lenses, validation moves
  artifact-templates.md       # artifact selection, doc section menu, ADR/option-note templates
evaluations/
  scenarios.md                # 10 pressure scenarios + run protocol + expected behaviors
  baseline-results.md         # RED: no-skill behavior, verbatim rationalizations
  skill-results.md            # GREEN/REFACTOR: with-skill results, loophole, fix, re-tests
  fixtures/setup-fixtures.sh  # recreates the two fixture repos under /tmp/esd-fixtures
  runs/                       # raw agent outputs (baseline, with-skill-iter1, with-skill-iter2)

Installing

Via the kroepke-marketplace:

/plugin marketplace add kroepke/claude-marketplace
/plugin install exploring-system-design@kroepke-marketplace

Or copy/symlink the skill directory where your agent discovers personal skills:

ln -s /path/to/exploring-system-design/skills/exploring-system-design \
  ~/.claude/skills/exploring-system-design

(The evaluations/ directory is development apparatus; it ships fine but the skill never loads it.)

Re-running the evaluations

bash evaluations/fixtures/setup-fixtures.sh
# then dispatch the prompts in evaluations/scenarios.md per its run protocol

Key behavioral choices (and why)

1. Six hard rules, everything else adaptive. Baseline testing showed a 2026-class agent fails architecture work through well-rationalized discipline breaks, not through missing knowledge — so only the discipline layer is absolute (no implementation mid-design; decisions made by their owners in the open; analysis not advocacy; no invented evidence; evidence-gated convergence; explicit-only implementation handoff). The activities (boundaries, drivers, alternatives, lenses…) are an explicitly reorderable toolbox, because ceremony was never the baseline failure and the spec forbids a mechanical funnel.

2. "Compress, don't capitulate" is the centerpiece of Rule 1. The only catastrophic baseline failure was full capitulation under time pressure (a 32-file scaffold). The skill therefore gives the agent a concrete fast path — name the 2–3 expensive-to-reverse decisions, conditional recommendation with labeled assumptions, park the rest — so resisting pressure never means stonewalling the user. If the user still directs implementation knowingly, that's their call; the decisions get stated in the open first.

3. Epistemic labeling (Decided / Proposed / Assumed / Open) is the central artifact mechanism. The subtlest baseline failures were silent decisions inside polished artifacts (a doc that "decides" BigQuery; defaults baked into a scaffold). Labels + a "Decisions required" section convert the documentation-theatre request ("complete and confident, no open questions") into something deliverable and honest at the same time.

4. Strong baseline behaviors were canonized, not reinvented. The baseline already produced default-plus-tripwires, superseded-decision history, decision-dependency maps, and safe-to-start lists in isolated runs. The skill names them as "moves" so they happen reliably instead of occasionally.

5. Requested documents ship this turn (REFACTOR addition). Iteration 1 revealed the predictable over-correction: an agent withholding an explicitly-requested doc revision pending a question round-trip. The questions-first rule now governs only unrequested designs; requested artifacts are delivered with provisional labels and the questions attached to the sections they'd change.

6. The description deviates from the originally proposed wording to satisfy the discoverability acceptance criteria (added: architecture, RFC, ADR, design review, design document, boundaries, trade-offs, quality attributes) and adds violation symptoms ("pressed to skip design and go straight to code") per skill-authoring guidance. It remains triggering-conditions-only — no workflow summary.