mikeparcewski/wicked-garden / skills/engineering
wicked-garden-engineering
VerifiedEngineering domain skill: code review, architecture analysis, debugging, implementation planning, documentation, release PRs and scaffolds. Use when: "review this code / file / diff" (quality, patterns, maintainability; --focus, --persona, --scenarios); "review the architecture of X" / "evaluate component boundaries, coupling, or layer violations" (--scope module|service|system); "debug this error / bug / unexpected behavior" (root cause, reproduction, fix, prevention); "plan this change" / "implementation plan with file changes, risks and tests before writing code"; "generate API docs / README / guide / inline comments" (--type api|readme|guide|inline) or "docs drifted from code"; "prepare a release PR" (never tags or publishes); "scaffold a new CLI / service / library". NOT for reviewing an AI agent system (agentic review), a UI (product ux-review), a go/no-go verdict (archetype review), greenfield design (the solution-architect worker) or scaffolding a new MCP server (wicked-garden-mcp-scaffold).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.7 KB |
| refs/arch.md | markdown | 4.5 KB |
| refs/conformance.md | markdown | 3.8 KB |
| refs/debug.md | markdown | 4.0 KB |
| refs/docs.md | markdown | 5.8 KB |
| refs/engineering-checklists.md | markdown | 2.7 KB |
| refs/engineering-templates.md | markdown | 1.2 KB |
| refs/plan.md | markdown | 4.1 KB |
| refs/release.md | markdown | 7.4 KB |
| refs/review.md | markdown | 7.4 KB |
| refs/scaffold.md | markdown | 5.6 KB |
refs/review.md
View on GitHub# review — senior engineering code review rubric
Bulletproof Standards (R1–R6 + T1–T6), severity guidelines, persona routing, and output format.
Use `engineering:review` for code-level review; use `engineering:arch` for component/system architecture review.
## Bulletproof Coding Standards — R1–R6
These are enforcement directives, not suggestions. Flag every violation. No exceptions.
- **R1: No Dead Code** — Flag unused imports, functions, variables, types, and unreachable branches.
Dead code decays, misleads, and costs. Delete it, or add a comment explaining why it stays.
- **R2: No Bare Panics** — Every function that can fail MUST return an error type or throw within
a handled context. No `panic()`, no unhandled exceptions, no `unwrap()` in production paths,
no `process.exit(1)` in library code. If it can fail, the signature must show it.
- **R3: No Magic Values** — All constants must be named. No bare numbers, strings, or config values
in logic. Examples to flag: `if retries > 3`, `timeout: 5000`, `color: '#1a1a2e'`, `z-index: 9999`.
Demand a named constant with a comment explaining the choice.
- **R4: No Swallowed Errors** — Every error catch must handle or propagate. Empty catch blocks,
`_ = err`, `pass`, and `console.log(err)` without user feedback are violations. "Log and continue"
counts only if the log includes the error detail and the function's contract allows partial failure.
- **R5: No Unbounded Operations** — All I/O (HTTP calls, DB queries, file reads, queue polls) MUST
have timeouts. No indefinite `await`, no missing `context.WithTimeout`, no fetch without
`AbortController` or `signal`, no infinite retries without backoff and ceiling. External calls
need a timeout AND a failure mode.
- **R6: No God Functions** — Functions over ~60 lines need extraction. More than 3 nesting levels
needs early returns or decomposition. If you can't describe what a function does in one sentence,
it does too much.
## Bulletproof Testing Standards — T1–T6
Apply when `--focus tests` or when reviewing test files directly.
- **T1: Determinism** — No date/time dependencies without injected clocks. No random without seed.
No order-dependent test suites. Same input → same result, always.
- **T2: No sleep-based sync** — No `sleep(200)` or `time.Sleep` as a synchronization mechanism.
Use explicit waits, callbacks, events, or polling with a timeout and an error on timeout.
- **T3: Isolation** — Each test sets up and tears down its own state. No shared mutable globals
between tests. No dependency on test execution order.
- **T4: Single assertion focus** — One logical assertion per test (multiple asserts on the same
subject is fine). Tests that assert five unrelated things make failures hard to diagnose.
- **T5: Descriptive names** — Test name should read as a sentence: `test_returns_empty_list_when_no_users`,
not `test_user_3`. Name should encode: subject + scenario + expected outcome.
- **T6: Provenance** — Each test should trace to a requirement, acceptance criterion, or bug ID.
Tests without clear purpose are maintenance debt. Note the gap as LOW severity.
## Agent overstepping — always flag
- Unrelated edits outside stated scope
- Commented-out code left in the diff
- Over-engineering / speculative generality (YAGNI violations)
- Scope creep: restructuring files not mentioned in the task
- Refactoring mixed into a bug fix (makes rollback impossible)
- Custom code that duplicates a built-in of the chosen stack (see below)
## Duplicates of a built-in — always flag
The user and the steering policies choose the framework or library (wicked-core rule
POL-2101). Flag every piece of custom code that re-implements something the chosen stack
already provides, even when the author gave a reason. Cite the code (`file:line`) and the
built-in it duplicates, from the stack's docs or source at the version the repo pins. Then
judge the author's reason against what the change actually needs. Reasons that can hold
include a feature the built-in lacks at the pinned version, a measured defect, a policy
conflict, or a behavior the change requires that the built-in does not give. The list is not
exhaustive. With no reason, or a reason that does not hold, the finding is at least MEDIUM.
Code that replaces the chosen framework with another is HIGH. Example: a change adds a
hand-written HTTP/OpenAPI layer to a fastmcp server. Check what the pinned fastmcp offers for
HTTP and OpenAPI, then judge the author's reason against that.
## Focus lanes (applied when `--focus` given)
| Flag | Deepen these areas |
|------|-------------------|
| `--focus security` | Auth/authz, input validation, SQL injection, credential handling, OWASP Top 10 |
| `--focus performance` | Hot paths, N+1 queries, missing indexes, unbounded ops, caching opportunities |
| `--focus patterns` | DRY, SOLID, naming, abstractions, module boundaries, coupling |
| `--focus tests` | T1–T6 standards, coverage gaps, flakiness risks, missing edge cases |
## Persona routing (`--persona <name>`)
1. Resolve the persona:
```bash
PERSONA_JSON=$(wicked-garden run scripts/_run.py scripts/persona/registry.py --get "${persona_name}" --json 2>/dev/null)
```
2. If found: apply the review through the persona's lens — flag what that persona's frame of
reference would catch (e.g. a security-focused persona finds auth gaps a general review might
rate LOW).
3. If not found: warn "Persona '{name}' not found — using default review lens" and fall through.
## wicked-scenarios (`--scenarios`)
For each Critical or High finding, emit a wicked-scenarios regression block:
```yaml
scenario: "{title describing the bug/issue}"
given: "{precondition}"
when: "{action that triggers it}"
then: "{expected behavior after fix}"
file: "{file}:{line}"
severity: "Critical|High"
```
## Standard output format
```markdown
## Engineering Review: {scope or file}
### Strengths
- {good pattern with file:line evidence}
### Issues
| Severity | Rule | Issue | Location | Recommendation |
|----------|------|-------|----------|----------------|
| CRITICAL/HIGH/MEDIUM/LOW | R1–R6 or T1–T6 | {description} | `{file}:{line}` | {concrete fix} |
### Architecture Notes
{Any structural observations — use engineering:arch for full analysis}
### Maintainability Concerns
{Long-term maintenance considerations}
### Agent Overstepping
{Any out-of-scope edits, commented-out code, or scope creep found — cite file:line}
### Duplicates of a Built-in
{Each piece of custom code that duplicates a built-in of the chosen stack: file:line, the built-in, the author's reason and whether it holds — or "none found"}
### Recommendations
1. {Highest priority with rationale}
2. {Secondary}
```
## Severity guidelines
- **CRITICAL**: Will cause data loss, security breach, or production outage
- **HIGH**: Will cause bugs, broken patterns, or major maintainability problems
- **MEDIUM**: Should fix; will accumulate tech debt; non-blocking
- **LOW**: Nice to have; style; minor improvements; provenance gaps
## Cross-specialist referrals
- Security deep-dive → `wicked-garden-platform-security-engineer`
- Testing strategy → `wicked-garden-qe-test-strategist`
- Architecture / structural trade-offs → the `wicked-garden-engineering-solution-architect` worker skill
- Frontend specifics (React hooks, CSS, a11y), backend specifics (DB, API design,
queues): handled inline — apply the relevant checklist from this skill's refs.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |