ai-quality

Files (4)

• SKILL.md
• bash-pitfalls.md
• deployment-patterns.md
• incident-patterns.md

SKILL.md (first lines)

# AI Quality & Best Practices

> **TL;DR:** These 5 pillars guide AI-assisted development. Apply them consistently for 30-50% better code quality and 40-50% fewer bugs.

## THE 5 PILLARS OF QUALITY AI DEVELOPMENT

### 1. DECOMPOSITION (Rules #1, #3, #9)
> **Break complex tasks into small, focused units.**

```
KEY LIMITS:
|- Max 50 lines per method
|- Max 7-9 objects in working memory
|- One responsibility per function
|- Separate signals — one variable, one question
```

**Why:** AI loses focus with complexity. Small units = better output.

**Separate-signals rule.** When a single variable answers two semantically distinct questions (e.g. "what to display" AND "is body non-empty"), refactoring one role silently breaks the other. Always extract independent signals for independent questions, even if they currently compute from the same source. The cost is one extra line at definition; the saving is not chasing regressions through downstream branches that read the variable as a proxy for something it no longer represents.

**Measuring the 50-line limit — discount template-literals and object-literal method blocks.** A naive `awk`/regex heuristic that spans "from one function keyword to the next" over-counts badly: it swallows a trailing object-literal whose methods follow the function, and it counts a function defined *inside* a `page.evaluate('...')` (or any embedded-script) template-literal string as part of the host method. Before flagging a >50-line finding, cross-check the actual brace span by reading the file — an orchestrator that hands work to a step-object below it, or one that embeds a DOM-walker as a string for the browser to run, is usually far shorter than the heuristic reports. Flag on the real span, not the keyword-to-keyword distance.

---

### 2. TEST-FIRST (Rules #2, #5, #6)
> **Tests are hallucination filters. Mock edges, not logic.**

```
SEQUENCE:
1. Write tests BEFORE code
2. Define "done" explicitly (DoD)
3. Cover corner cases upfront
4. STRICT mocking: edges only, NO data fitting
```

**Why:** Tests catch AI mistakes. No tests = no safety net.

---

### 3. ARCHITECTURE-FIRST (Rules #7, #8)
> **Approve structure before coding.**

```
APPROACH:
1. Create skeleton with stubs
2. Review architecture
3. Implement one method at a time
```

**Why:** Bad architecture = wasted work. Validate first.

---

### 4. FOCUSED WORK (Rules #10, #11, #12)
> **Narrow context improves quality.**

```
PRACTICES:
|- Review one method at a time
|- Define clear boundaries (what we DON'T do)
|- Verify AI can solve before starting
|- Wire ALL planned features in first pass — if code/prompts are ready
   and wiring is <30 min, do it. "Low risk deferral" is still deferral.
|- Decompose multi-clause success criteria — a criterion joined by "and"
   or listing N independent requirements is N checks. Close each sub-clause
   with its own named test and verify each before marking the wish done.
   One green test on the first clause does NOT satisfy a two-clause wish.
|- Authorization prompts to user: 1 sentence risk + 1 yes/no question.
   Threat models → docs, not interactive prompt.
```

**Why:** Broad context = scattered results. Focus = precision.
Source (auth UX): prior incident — user requested simpler prompts after a 7-option authorization table.
Source (wire-all): prior incident — dedup/rerank deferred as "low risk", user challenged, wiring took <15 min.
Source (decompose): prior incident — a "select backend AND inject per-role allowed-tools" wish had its first clause implemented and the second silently skipped (the registry declared the tools but no consumer read them); the partial surfaced only at the expectations gate, costing one extra implement→review round.

---

### 5. CONTEXT MANAGEMENT (Rules #4, #13, #14, #15)
> **Right information at right time.**

```
ELEMENTS:
|- Gather requirements BEFORE coding
|- Document transaction isolation needs
|- Structure datarim hierarchically
|- Engineer prompts carefully
```

**Why:** Bad context = bad output. Quality in = quality out.

---

### 6. LINT-ON-THE-SPOT
> **Run project linters after each TDD code-change step, before moving to the next stub/method.** Defers to `/dr-compliance` only when the project has no auto-detectable linter — not when findings need fixing.

```
AUTO-DETECTION PATTERNS (check manifests in order of precedence):
1. eslint / prettier → `package.json` (devDependencies or scripts)
2. ruff / flake8 / pylint → `pyproject.toml`, `ruff.toml`, `setup.cfg`
3. clippy / rustfmt → `Cargo.toml` (under [lints] or as dev-dependency)
4. golangci-lint → `.golangci.yml` or `go.mod` + `tools.go`
5. rubocop → `.rubocop.yml`
6. Any linter configured in project root config files → detect by extension
```

**Procedure:**
1. After each TDD RED-GREEN-REFACTOR cycle, run the auto-detected linter against changed files.
2. Fix findings immediately — do not accumulate lint debt.
3. If no auto-detectable linter exists: skip and note in the task description that lint discipline is manual.
4. Never defer lint fixes to `/dr-compliance`: that stage assumes a clean baseline.

**Why:** Lint findings discovered at compliance time force a fixup commit outside the TDD loop, breaking the RED-GREEN-REFACTOR cadence. Each lint rule is a potential bug that was visible at code time but deferred to a stage that expects cleanup, not bug-fixing.

Covered by: `commands/dr-do.md` § Step 7 ACTION — Lint-on-the-spot (MANDATORY).

---

From Arcanada-one/datarim, MIT.

More from Arcanada-one/datarim