HeyEddi-com Engineering Excellence
Simple solutions that scale: documented so the next agent does not over-build or repeat work.
All artifacts go under .heyeddi/docs/: never repo root.
When to use
- After a feature ships: capture how it works
- Before adding abstractions: check reuse catalog
- Refactor / architecture review: KISS, YAGNI, SOLID
- User asks: "don't over-engineer", "document the system", "engineering notes"
Subagents (default)
See reference/subagents.md. Delegate audit_engineering.py and doc init to Task shell. Main chat interprets findings and updates living docs.
Pipeline
init_engineering_docs → .heyeddi/docs/engineering/{architecture,reuse-catalog,decisions}.md
implement / refactor
audit_engineering → .heyeddi/docs/engineering-audit-<date>.md
append_decision → ADR when trade-off is non-obvious
Instructions
- First time in project:
python scripts/init_engineering_docs.py --project-root <root> - While coding: read
reuse-catalog.mdbefore new components/composables/services - After meaningful change: update
architecture.mdmodule map and add reuse rows - Non-obvious trade-off:
append_decision.py --title … --context … --decision … - Before merge (non-trivial):
audit_engineering.py --check(add--strictfor warns)
Principles (how we enforce)
| Principle | Skill behavior |
|---|---|
| KISS | Warn on oversized files; prefer flat modules |
| YAGNI | Flag abstraction names without clear reuse |
| DRY | Maintain reuse-catalog.md; chain @no-duplicate-ui for UI |
| SOLID | Warn on fat routers; views thin, services fat |
| Testable | Note views missing smoke specs |
.heyeddi/ outputs
| Path | Purpose |
|---|---|
.heyeddi/docs/engineering/architecture.md |
System map, data flow, boundaries |
.heyeddi/docs/engineering/reuse-catalog.md |
What exists: do not rebuild |
.heyeddi/docs/engineering/decisions.md |
Engineering ADRs (not design log) |
.heyeddi/docs/engineering-audit-<date>.md |
Point-in-time audit report |
Design decisions stay in .heyeddi/design.md Decision log: do not mix.
Chain
@project-engineering: scaffold first@composable-patterns/@backend-type-bridger: after architecture notes exist@pre-merge-gate: final CI; this skill is advisory + docs