dirien/yet-another-agent-harness / .claude/skills/design-principles
design-principles
VerifiedAudit a codebase against well-known software design principles: SOLID, DRY, YAGNI, KISS, Law of Demeter, Separation of Concerns, Composition over Inheritance, and the code-relevant 12-Factor subset. Scores findings by impact and effort, runs adversarial debate on contested violations, and generates a prioritized DESIGN_AUDIT.md. Use when reviewing code quality beyond what linters catch, assessing design health before a refactor, or onboarding to an unfamiliar codebase. Can be invoked standalone or delegated from tech-debt.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.0 KB |
| references/principles-guide.md | markdown | 10.8 KB |
| references/report-template.md | markdown | 4.2 KB |
references/report-template.md
View on GitHub<!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
# Report template
Template for DESIGN_AUDIT.md generated by the `design-principles` skill.
## Impact levels
| Impact | Definition | Example |
| ------ | ---------- | ------- |
| LOW | Minor design smell, low reader confusion | Single extra abstraction level |
| MEDIUM | Slows feature development or increases test burden | Mixed concerns in a handler |
| HIGH | Blocks testing, causes recurring bugs, or requires shotgun surgery | No interfaces at layer boundaries |
| CRITICAL | Causes production risk or blocks meaningful refactoring | Hardcoded credentials, untestable core logic |
## Effort levels
| Effort | Time | Example |
| ------ | ---- | ------- |
| S | < 1 day | Extract constant, add delegation method |
| M | 1–5 days | Introduce interface, split a God file |
| L | 1–2 weeks | Restructure a layer, add DI across a subsystem |
| XL | > 2 weeks | Rewrite a core module to untangle concerns |
## Priority calculation
| Priority | Criteria | Action |
| -------- | -------- | ------ |
| P1 | HIGH/CRITICAL impact + S/M effort | Fix this sprint |
| P2 | HIGH impact + L effort, or MEDIUM + S/M effort | Fix next sprint |
| P3 | MEDIUM impact + L effort | Fix this quarter |
| P4 | LOW impact, any effort | Backlog |
## Principle scores (0–10)
| Score | Level | Description |
| ----- | ----- | ----------- |
| 0–2 | Excellent | No significant violations found |
| 3–5 | Good | Minor violations, not blocking progress |
| 6–8 | Needs work | Multiple violations slowing development |
| 9–10 | Critical | Pervasive violations, blocking refactoring |
Score each principle on how severely its violations impact the
codebase, not just how many violations exist. One CRITICAL finding
scores higher than five LOW findings.
## DESIGN_AUDIT.md template
```markdown
# Design Principles Audit
Generated: YYYY-MM-DD
Project: [project name]
Language(s): [detected languages]
Scope: [full / module name / changed files]
## Executive Summary
Overall design health: X/Y (sum of applicable principle scores /
maximum possible)
Principles assessed: X of 11
P1 items requiring immediate attention: X
## Scorecard
| Principle | Score | Impact | Top Finding |
| --------- | ----- | ------ | ----------- |
| Single Responsibility | X/10 | ... | ... |
| Open/Closed | X/10 | ... | ... |
| Liskov Substitution | X/10 | ... | ... |
| Interface Segregation | X/10 | ... | ... |
| Dependency Inversion | X/10 | ... | ... |
| DRY | X/10 | ... | ... |
| YAGNI | X/10 | ... | ... |
| KISS | X/10 | ... | ... |
| Law of Demeter | X/10 | ... | ... |
| Separation of Concerns | X/10 | ... | ... |
| Composition over Inheritance | X/10 | ... | ... |
| 12-Factor (config/logs/stateless) | X/10 | ... | ... |
*N/A: [principle] — not applicable to this language/paradigm*
## Detailed Findings
### [Principle Name] (Score: X/10)
#### Finding N: [Short title]
- **Impact**: [LOW/MEDIUM/HIGH/CRITICAL]
- **Effort**: [S/M/L/XL]
- **Priority**: [P1/P2/P3/P4]
- **Location**: `file.go:42` (or `src/service/user.ts:100–150`)
- **Evidence**: [What was found — quote the code or describe the
pattern with specifics]
- **Remediation**: [Concrete action: extract X into Y, introduce
interface Z, move W to package Q]
### Adversarial Debate — Contested Findings
#### Debated Finding N: [title] (`file.go:line`)
**Current code** (5–10 relevant lines, indented):
// paste code here
**Red (refactor)**: [argument + proposed change]
**Blue (keep)**: [argument with specific context reasoning]
**White (verdict)**: REFACTOR | KEEP | ADD JUSTIFICATION
[one-paragraph reasoning]
[If REFACTOR: include the proposed diff or refactoring steps]
[If ADD JUSTIFICATION: include the replacement comment text]
## Remediation Roadmap
### This Sprint (P1)
- [ ] [Action item — specific file/function/scope]
### Next Sprint (P2)
- [ ] [Action item]
### This Quarter (P3)
- [ ] [Action item]
### Backlog (P4)
- [ ] [Action item]
## Success Metrics
- [Metric]: [current value] → [target value]
- Example — Interfaces at service boundaries: 0 → 5
- Example — Functions mixing I/O and business logic: 12 → 0
- Example — Hardcoded URLs in source: 8 → 0
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |