Skip to content

dirien/yet-another-agent-harness / .claude/skills/design-principles

design-principles

Verified

Audit 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.

FileKindSize
SKILL.mdskill md7.0 KB
references/principles-guide.mdmarkdown10.8 KB
references/report-template.mdmarkdown4.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
```
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall