| name | engineering-wisdom |
| description | Provide an explicitly requested, repository-grounded engineering review using contextual heuristics for code clarity, SOLID and design, testing, refactoring, architecture, and professional practice. Use only when the user invokes `$engineering-wisdom` or explicitly asks for this installed engineering-wisdom pack; do not turn its advice into repository policy or automatically rewrite an application architecture. |
Engineering Wisdom
Give practical advice without treating a school of thought as universal law.
Repository intent, code, tests, and observed behavior remain authoritative.
Establish Scope
- Read
AGENTS.md, docs/WORKFLOW.md, and only the repository material
relevant to the request.
- Confirm that the user explicitly invoked this skill. Installation alone is
not activation.
- Determine whether the request is advice/review or an authorized change.
Keep reviews read-only. For changes, follow repository authority and
validation rules before editing.
- Read references/heuristics.md. Select only
heuristics that match observed evidence. Read
references/sources.md when attribution or the
intellectual basis matters.
- When the request crosses a host boundary, inspect the composition root,
external input, adapter semantics, shipped artifact, and cumulative state
that are relevant. Do not assume isolated core tests prove those boundaries.
Review From Evidence
For each material finding, keep these fields separate:
- Observation: A concrete repository fact with a path, symbol, test,
command result, or behavior.
- Heuristic: One named rule of thumb from the catalog and why it may apply.
- Trade-off: Counter-pressure, cost, or a condition under which following
the heuristic would make the system worse.
- Proposed repository-owned enforcement: Either
None, or a separately
labeled proposal naming the repository owner, authority still required,
possible mechanism, and removal condition. Never describe advice as an
existing rule unless repository evidence already establishes it.
- Verification: A focused observation or executable check that could
confirm or falsify the recommendation. Match proof to the claim: test pure
policy in isolation, startup at the composition root, and delivery through
the artifact users actually load.
Rank findings by user impact and change risk. Prefer one concrete example over
several abstract claims.
Advise Before Enforcing
- Do not rewrite application architecture merely because a heuristic suggests
a different shape.
- Do not introduce interfaces, layers, tests, linters, size limits, coverage
targets, or dependency rules without repository-owned authority.
- Propose the smallest reversible experiment when evidence is incomplete.
- Preserve a deliberate duplication, coupling, integration test, or framework
dependency when its local benefit outweighs the heuristic.
- Say when no catalog heuristic materially improves the observed code.
If the user requests implementation and authority is sufficient, make the
smallest coherent change and run the repository's own proof. Keep the review
rationale separate from the evidence that the change works.
Response Shape
Start with the outcome in one sentence. Then report only material findings:
Finding: <specific effect>
Observation: <repository evidence>
Heuristic: <contextual rule of thumb and applicability>
Trade-off: <counter-pressure or harm condition>
Proposed repository-owned enforcement: None | <owner, missing authority,
mechanism, removal condition>
Verification: <command, test, measurement, or observation>
End with unresolved risks or None. Do not add a policy checklist by default.
