QE Methodology

QE Methodology

Formalized quality-engineering workflow: Devil's Advocate review paired with agentic-QE fleet patterns. Full spec: docs/QE-METHODOLOGY.md.

Every code wave follows a Build → Gate → Hunt → Fix cycle. Quality is enforced at every transition — not bolted on at the end.

┌─────────┐    ┌──────────────┐    ┌──────────────────┐    ┌─────────┐
│  BUILD  │───►│ QUALITY GATE │───►│ DEVIL'S ADVOCATE │───►│   FIX   │
│ (Wave)  │    │  (Go/No-Go)  │    │  (Adversarial)   │    │ (Triage)│
└─────────┘    └──────────────┘    └──────────────────┘    └────┬────┘
     ▲                                                          │
     └───────────────────── next wave ◄────────────────────────┘

Phase 1 — Build

Sub-agents implement features from ADR-defined issues.

• One ADR wave at a time — prevents rate limits and git conflicts.
• Sequential over parallel when quality matters more than speed.
• Verify npx tsc --noEmit is clean before proceeding.
• Each sub-agent gets: the ADR text, the issue description, existing code context, and shared types.

Testability check (pre-build) — score each issue before writing code:

Factor	Score	Criteria
Pure functions	+2	No side effects, deterministic
Injected dependencies	+1	Constructor/parameter injection
Global state	−2	Singletons, module-level mutation
Async chains	−1	Nested promises, callback depth > 2
External I/O	−1	File system, network, database

Threshold: score ≥ 0 to proceed; < 0 requires a design review first.

Phase 2 — Quality Gate

A formal go/no-go before adversarial review.

Metric	Foundation Wave	Feature Wave	Integration Wave
TypeScript errors	0	0	0
Exported without types	0	0	0
Functions > 80 lines	≤ 2	≤ 3	≤ 5
any type usage	0 new	0 new	0 new
Barrel exports updated	Required	Required	Required
ADR compliance	Full	Full	Full

• PASS → proceed to devil's advocate.
• CONDITIONAL → fix gate failures first, re-check.
• FAIL → rebuild the wave (should be rare with good ADRs).

Phase 3 — Hunt (Devil's Advocate)

An adversarial pass whose mandate is assume defects exist; find them. Reviewers actively try to break the change and verify every concrete claim against source — a "tests pass / typecheck clean" claim is confirmed by running it, not trusted. For network-facing or safety-relevant code (protocol servers, control-parameter mutation, anchoring), the review takes an attacker's mindset: open-proxy/SSRF, fail-open defaults, unauthenticated actuation, replay, injection.

Risky designs are attacked before implementation via adversarial-design-review, so effort isn't spent building something that won't survive review.

Phase 4 — Fix (Triage)

Findings are triaged by severity (critical / high / medium / low) and remediated — critical/high first. Only after the adversarial pass clears is work approved and merged.

Conventions

• PR titles: wave-N/adr-NNNN-topic, qe-fixes/{critical-high,medium,refactor-low}.
• Issue prefix: [QE] for adversarial findings ([QE] bug:, [QE] security:).
• Severity vocabulary: critical / high / medium / low.
• Local bar before proposing: npx tsc --noEmit clean and the relevant test project green.
• Agent attribution: every PR carries City-Agent: <agent-name> (see For AI Agents).

The charter behind this practice — an "Agentic Engineering" organization where adversarial review forces robustness — is in docs/CHARTER.md.