audit-stack

Files (1)

• SKILL.md

SKILL.md (first lines)

Audit `preferences.md` against the problem described in `docs/input/` to check whether the stack choices are orthodox, idiomatic, and right-sized for the project.

## When to use

- Before `/expand` when starting a new project and you want a sanity check
- When input docs describe a problem domain you haven't built in before
- When you suspect the default stack in preferences.md might be over- or under-engineered for this problem
- When a client has strong opinions about technology and you want to validate them
- After `/distill` when the structured requirements reveal integration constraints you didn't anticipate

## Steps

1. Read `preferences.md` — extract the current stack preferences, deploy targets, and conventions
2. Read all files in `docs/input/` — understand the problem domain, integrations, constraints, scale, and user expectations
3. Infer the likely quality tier (shed / house / skyscraper) from the input docs

4. Evaluate the stack against these axes:

### Orthodoxy

Is this the **standard, boring choice** for this problem domain? What would a senior principal engineer at a serious company reach for?

- If input docs describe a CRUD web app and preferences say Rust + WASM → flag it
- If input docs describe a high-performance data pipeline and preferences say Python → note the tradeoff
- If input docs describe a simple CLI and preferences say full-stack framework → flag over-engineering
- Check whether the ecosystem for the chosen stack has mature libraries for the integrations described in input docs

### Idiomaticity

Do the conventions in preferences.md align with how the chosen stack's community actually works?

- Build tools (is `uv` standard for Python? Is `trunk` standard for Rust WASM? etc.)
- Project structure conventions
- Testing patterns
- Deployment patterns for the target platform

### Right-sizing

Is the stack complexity proportional to the quality tier?

- Shed → single language, minimal deps, simple deploy
- House → reasonable stack, automated deploy, standard infra
- Skyscraper → justified complexity, staged deploy, monitoring, the works

Flag if the stack is **over-engineered** for the tier (common) or **under-engineered** (rare but dangerous).

### Compatibility

Do the chosen components work well together?

- Language ↔ framework ↔ deploy target ↔ database ↔ auth provider
- Are there known friction points? (e.g., Rust + serverless cold starts, Python + WASM, etc.)
- Do the external integrations in the input docs have good library support in the chosen language?

### Deploy target fit

Does the deploy target match the application type?

- Static site → GitHub Pages ✓, Docker on VPS ✗ (overkill)
- API server → Docker on VPS ✓, GitHub Pages ✗ (impossible)
- CLI tool → binary release ✓, Docker ✗ (wrong model)
- Background worker → cron/queue ✓, GitHub Pages ✗

5. Produce an audit report:

```markdown
## Stack Audit — [date]

**Input docs reviewed**: [list files]
**Inferred quality tier**: [shed / house / skyscraper]
**Current stack**: [from preferences.md]

### Verdict: [GOOD FIT / MINOR CONCERNS / RECONSIDER]

### Orthodoxy

[Is this the boring, standard choice? What would the community reach for?]

### Right-sizing

[Is the complexity proportional to the tier?]

### Compatibility

[Do the components play well together? Library support for integrations?]

### Deploy Target

[Does the target match the application type?]

### Recommendations

- [Specific, actionable suggestions — or "No changes needed"]

### If changing stack

[Only if recommending a change: what to update in preferences.md and why]
```

6. Present the report to the user. **Do not modify preferences.md automatically** — stack changes are a human decision.

7. If the user agrees with changes, update preferences.md accordingly.

## Rules

- **Never auto-change preferences.md.** Present findings, let the user decide.
- **Bias toward the current stack.** Switching stacks has high cost. Only recommend a change if there's a clear mismatch, not just a marginally better option.
- **"Orthodox" means what the community uses**, not what's theoretically optimal. If 80% of Python web apps use FastAPI or Django, that's orthodox. If 3% use a custom async framework, that's not.
- **Consider the human.** If preferences.md reflects the user's expertise, the "orthodox" choice for them might differ from the industry default. A Rust expert building a web app in Rust is fine; a Python expert doing the same thing should probably use Python.

From RCSnyder/lights-out-swe-plugin, MIT.

More from RCSnyder/lights-out-swe-plugin