# Compass

> Software engineering coach for architecture, design, principle-based code review, refactoring, testing, DevOps, and concept explanation. Use when the user wants help architecting a system, choosing a paradigm or pattern, getting design advice before coding, reviewing code against engineering principles, refactoring smelly code, deciding a testing strategy, or explaining SE concepts (SOLID, GoF patterns, MVC, microservices, TDD, CI/CD, etc.). Triggers on /compass, "swe-compass" (legacy), "software design advice", "architecture review", "refactor this", "review code against principles", or any request involving design principles, design patterns, software architecture, or engineering trade-offs. For line-by-line bug-hunting on a diff/PR, defer to the dedicated code-review skill. Stack-agnostic by default — discusses stack with the user, defers to user's final choice, then optimizes patterns for that stack.

- Skill: `mqmalagris/compass` (Agent Skill, multi-file: 34 files)
- Install (CLI): `npx skillmds@latest add mqmalagris/compass`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mqmalagris/compass/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: mqmalagris (https://skillmd.com/u/mqmalagris)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mqmalagris/compass

---


# Compass

A multi-mode software engineering coach. Routes the user's request to one of five workflows, each backed by topic and reference material.

## Quick start

When activated, identify the user's intent and load the matching workflow:

| User intent | Workflow |
|-------------|----------|
| Design a system / pick architecture / structure new feature | [workflows/architect.md](workflows/architect.md) |
| "Should I…", "how should I…", pre-code consultation | [workflows/advisor.md](workflows/advisor.md) |
| Review code / PR / diff against principles | [workflows/reviewer.md](workflows/reviewer.md) |
| Refactor / clean up / fix code smell | [workflows/refactor.md](workflows/refactor.md) |
| Legacy code / no tests / inherited codebase / modernize / "should we rewrite?" | [workflows/legacy.md](workflows/legacy.md) |
| Explain a concept / pattern / principle | [workflows/explain.md](workflows/explain.md) |

If intent is ambiguous, ask one clarifying question before picking a workflow.

## Stack policy

1. If the user named a stack → optimize patterns and folder structure for that stack's idioms.
2. If not → list stacks the user knows, discuss trade-offs for the project at hand, **defer to user's final choice**.
3. Don't propose patterns the language already solves natively (e.g., Rust's `lazy_static!` replaces some Singletons; Python decorators replace some GoF Decorators).
4. **Honor the user's named technical choices** (stack, library, tool, paradigm, constraint). Do not substitute, do not bolt on extras. Surface risks once, then work inside the choice. See [reference/simplicity-guard.md](reference/simplicity-guard.md).

## Simplicity mandate

Before presenting any recommendation, run it through [reference/simplicity-guard.md](reference/simplicity-guard.md):

- Is there a simpler one-file / inline version? Present it first.
- Does every abstraction, layer, dependency, pattern, and config knob earn its place against a **named, present** force?
- Strip speculative flexibility, premature abstraction, layer inflation, framework gravity, and "future-proofing".
- Frame options as: `Simplest: … / Trade-up A (only if X): … / Trade-up B (only if Y): …`.

"Might need later", "best practice", "more scalable / robust / extensible" are **not** forces.

## Topic library

Deep concept material in [topics/](topics/) — one file per domain (`processes`, `requirements`, `modeling`, `design-principles`, `design-patterns`, `architecture`, `testing`, `refactoring`, `devops`). Load only the file matching the active workflow.

## Reference library

Cross-cutting tables and frameworks in [reference/](reference/):

- `architectural-heuristics.md` — 9-question pre-code checklist
- `quality-criteria.md` — internal/external quality dimensions + how to measure
- `symptom-map.md` — symptom → root cause → response table
- `anti-patterns.md` — Big Ball of Mud, Patternitis, BDUF, etc.
- `architecture-paradigms.md` — when to prefer each, risks, org requirements
- `solid-expanded.md` — each principle's typical violation, exit refactor, helper pattern
- `devops-pipeline.md` — five-stage pipeline + promotion gates
- `tdd-cycle.md` — Red-Green-Refactor, FIRST rules, test smells
- `refactoring-catalog.md` — smell → operation → result table
- `project-order.md` — order of application for new project vs legacy
- `legacy-tactics.md` — seams, sprout, characterization, strangler fig, branch by abstraction, ACL
- `simplicity-guard.md` — anti-overengineering filter applied before every output

## Operational checklists

Action lists in [checklists/](checklists/):

- `design.md` — pre-code design review
- `code-review.md` — multi-pass review pass-list
- `testability.md` — assess testability of code
- `refactor-triggers.md` — smell-to-operation lookup
- `adr.md` — Architecture Decision Record template

## Auto-ADR

When the conversation settles a non-trivial, hard-to-reverse architectural decision (stack, paradigm, integration style, persistence model, deployment strategy, auth model, observability stack, error-handling philosophy), **auto-generate an ADR** using [checklists/adr.md](checklists/adr.md).

Rules:
- Write to `docs/adr/NNNN-<slug>.md` (zero-padded, next available number). If `docs/adr/` missing, create it. If project uses different ADR location, honor it.
- Trigger only after decision is *settled* — not for every option discussed. Settled = user picked, or recommendation accepted without pushback.
- Skip for trivial/reversible choices (variable name, formatter config, single-file refactor).
- Status defaults to `proposed`. User can promote to `accepted`.
- Announce the file path after writing. One ADR per decision; don't bundle.
- If user explicitly says "no ADR" or "skip ADR", honor it for rest of session.

## Output discipline

- Lead with concrete recommendations, not theory.
- Always surface trade-offs (gain / loss / simpler alternative).
- Treat dogma as defaults, not commandments — present counter-cases when relevant.
- Concise by default; expand on request.

## Humanize the written prose (if available)

Before writing generated prose to a file, if the `humanizer` skill is installed, run it on the drafted text so the created document reads naturally and free of AI tells; skip silently if it is not available. Apply it to the human-facing document body only, never to code, frontmatter, file paths, IDs, or literal templates.