| name | scan-for-defects-mechanical |
| description | Run the early, mechanical subset of the multi-pass defect scan — local bugs that do not need contracts or protocols context to spot. Run after the architecture phase, before contracts. Covers logic and correctness, error handling and resilience, and configuration and environment hazards. The semantic subset (concurrency, security, API contract violations) runs later in the `defect-scan-semantic` phase, after protocols. |
Scan For Defects — Mechanical Pass
This phase runs the early, mechanical half of the defect-scan methodology. It catches the bugs that are visible from local code reading without needing the contracts or protocols phases to be done first. The deeper passes (concurrency, security, API contract violations) live in the later defect-scan-semantic phase.
The source code to analyze is in the parent directory (../ relative to .codecarto/).
Prerequisites
Required:
findings/architecture/architecture-map.md — for the layer map and public surfaces.
You do not need contracts or protocols for this phase. If those exist already, skim them as bonus context, but do not block on them — the mechanical pass is by design context-light.
Pass Execution Order
Run these three passes sequentially. Read the pass file, scan the source, record findings, then move to the next pass. Each pass file is the same one used by the legacy defect-scan phase — only the subset is different.
| Pass | File | Focus |
|---|
| 1 | findings/defect-scan/passes/01-logic-and-correctness.md | Dead code, boundary errors, null handling, boolean logic, control flow |
| 2 | findings/defect-scan/passes/02-error-handling.md | Swallowed errors, missing cleanup, uncaught exceptions, retry gaps |
| 6 | findings/defect-scan/passes/06-config-and-environment.md | Hardcoded values, missing validation, dangerous defaults, OS assumptions |
Passes 3, 4, and 5 are deferred to defect-scan-semantic because they benefit from contracts/protocols context.
Prioritization
Use the architecture map to decide emphasis:
- Pure library with no config? Skim pass 6.
- Heavy generic-types or branching logic? Spend extra time on pass 1.
- No surfaced error model in architecture? Pass 2 may surface that gap as a finding.
Evidence and Severity Classification
Use the same scheme as the legacy defect-scan SKILL:
- Evidence levels:
observed fact, strong inference, open question.
- Severity:
critical, high, medium, low.
- Action (pre-porting pipelines):
fix before porting, port differently, leave behind.
See findings/defect-scan/SKILL.md for the full criteria; this phase intentionally does not duplicate them.
Output
Write findings to the primary output using templates/mechanical-defects.md. Organize by pass, then by severity within each pass. End with a summary table covering only passes 1, 2, and 6.
If the semantic phase later finds related defects, those go in its own report — do not amend this one after this phase is complete.
What to defer to the semantic phase
- Concurrency, race conditions, and lock issues → pass 3 in
defect-scan-semantic.
- Auth, input validation, secrets, and trust boundary defects → pass 4 in
defect-scan-semantic.
- API/spec/state-machine drift → pass 5 in
defect-scan-semantic.
If you spot something semantic during this phase, record it as a carry_forward entry in your phase handoff at scratch/handoffs/defect-scan-mechanical.yaml with target_phase: defect-scan-semantic. Completion applies it to workflow/status.yaml, and the semantic phase receives it as a routed item in its prompt. Listing it only in your report's routing table does not route it.
