Sacco socratic architecture

Skill adrien-sacco/sacco-skills/skills/sacco-socratic-architecture

Make architecture and design decisions by reasoning through trade-offs out loud instead of jumping to an answer. Use when choosing between technical approaches, weighing build-vs-buy, designing a cross-service integration, or when you want Claude to think a decision through with you step by step. Triggers: "how should we architect...", "help me decide between...", "what's the right approach for...", "think through the trade-offs", "reason this through with me".From its SKILL.md

Install

npx -y skills add adrien-sacco/sacco-skills --skill sacco-socratic-architecture

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.6 KB, as published. Nobody here has run it

Skill: Socratic Architecture Session

What It Is

Instead of telling Claude the answer, you withhold it and guide Claude to derive it through questioning. This produces deeper architectural understanding and avoids the "parrot-back" anti-pattern where Claude just echoes your instructions.

When to Use

Architecture decisions with multiple valid approaches
Cross-team boundary decisions (who owns what?)
When you want Claude to internalize a principle, not just follow an instruction
Shared concern extraction (when a module outgrows its repo)
Technology selection (build vs buy vs integrate)

The Approach

Step 1: Present the Situation (Not the Answer)

"We have this schema vendored in the infra repo. But now the app service
also needs it. What do we do?"

NOT: "We should publish it as an OCI artifact."

Step 2: Let Claude Propose (Accept or Redirect)

Claude will propose something. If it's wrong or shallow, redirect:

"Think deeper. What's the architectural principle here?"
"You're solving a solved problem. What existing tooling handles this?"
"That's a half-answer. What are the gotchas?"

Step 3: Validate Understanding

"Good. Now what does that mean exactly? What are the edge cases?"
"And what about the consumers? How do they discover this?"

Step 4: Codify the Decision

Once Claude has derived the correct approach:

"Write this up as an ADR (Architecture Decision Record) and put it in docs/decisions/"

Example

A Rust backend service needed a CRD JSON schema that was vendored in the infrastructure repo. Rather than prescribing the solution, the conversation was framed as:

"The schema lives in the infra repo. But now this service also needs it. I won't tell you the answer — think about what to do when a concern outgrows its original repo."

Claude initially proposed vendoring the schema directly. Redirected:

"Think deeper. We already have it in infra. What's the architectural principle when something becomes shared?"

Claude derives: publish the schema as an OCI artifact to GHCR, consumed by the service via ORAS.

"Voila. Now think through what that means exactly. What are the gotchas?"

Claude identifies: versioning strategy, consumer discovery, schema validation, CI integration for publication on merge.

This exchange produced a fully-reasoned solution with edge cases a prescriptive instruction would have skipped, and an ADR that captured the WHY, not just the WHAT.

Why It Works

Claude retains principles better when it derives them vs being told
Forces Claude to think about trade-offs, not just the happy path
Catches shallow thinking early ("that's a half-answer")
Produces better ADRs because Claude understands the WHY, not just the WHAT

Anti-Pattern: The Opposite

Telling Claude exactly what to do produces compliance, not understanding:

"Publish the schema as an OCI artifact to GHCR using ORAS.
Add a CI step that publishes on merge to main.
Add an ORAS pull step to the service Dockerfile."

This works for one-off tasks but doesn't build Claude's ability to make similar decisions independently in the future.