Explanation¶
Background, principles, and design choices. Aimed at readers who want context.
Code review principles¶
SOLID, structural conventions, error handling, performance, and security.
| Document | Description |
|---|---|
| General principles | SOLID, KISS, composition over inheritance, God class detection |
| Structural conventions | One class per file, test mirroring, naming, test splitting |
| False positive prevention | Suppression rules to avoid noisy reports |
| Error handling | Custom exceptions, hierarchy, specific catches, finally cleanup |
| Performance | Lazy loading, generators for large datasets |
| Security | Parameterized queries, output escaping, input validation, secrets in env |
Language-specific patterns¶
Strategy autodiscovery, Protocol vs ABC, interface vs abstract, traits.
| Document | Description |
|---|---|
| Python review patterns | Strategy autodiscovery, Protocol vs ABC |
| PHP review patterns | Strategy autodiscovery, interface vs abstract, traits |
Documentation principles¶
Docs-as-code, README structure, API docs, changelogs, ADRs, and drift prevention.
| Document | Description |
|---|---|
| Documentation standards | Docs-as-code principles and the four types of documentation |
| README structure | README best practices and anti-patterns |
| API documentation | Function, class, and module documentation patterns |
| Changelog conventions | Keep-a-Changelog format and rules |
| Architecture Decision Records | ADR format and best practices |
| Drift prevention | Coupling strategies, CI gates, review checklists |
Architecture Decision Records¶
Design decisions and their rationale, captured as numbered ADRs.
| Document | Description |
|---|---|
| ADR-0001 Meta-skill dispatch | Single meta-skill with subcommand dispatch |
| ADR-0002 Settings.json | Single config source for project-wide settings |
| ADR-0003 Diátaxis framework | Diátaxis framework for documentation structure |
| ADR-0004 Python stdlib only | Scanners use Python stdlib only, no external deps |
| ADR-0005 Parallel subagents | Review orchestrator with parallel subagents |
| ADR-0006 Setup guard | Setup guard pattern for settings staleness |
| ADR-0007 Language-neutral engine | LanguageEngine protocol with ModuleInfo model |
| ADR-0008 Skills directory | Sub-skills grouped under skills/ directory |
| ADR-0009 Python scripts | Inline shell replaced by testable Python scripts |
| ADR-0010 ADR distiller | ADR distiller for extracting accepted directives |