Defect Detection

Defect Detection

Agent-driven, method-by-method inspection. Tools gather context; rules, history, and evidence produce findings; users confirm or reject them.

Purpose: find real quality issues. Do not skip methods, skip steps, or soften a real defect.

Write-back rule: a real defect is written as bugStatus=6 (suspected) or 7 (improvement), whether or not it sits inside the current diff.

Execution mode: light vs strict

build-detection-plan sets the mode from total changed lines (additions + deletions):

API required fields stay the same in both modes: thinking, processSteps, fileCodes, content (line numbers + prefix), tagId.

Documents (load on demand)

Load each Phase file at most once per task. Do not re-read references/phase1-preparation.md / references/phase2-detection.md / references/phase3-close.md / references/feedback.md after the first load unless a gate cites a section you have not read. After prep-and-plan / trivial-method-filter, enter detection without reloading Phase 2. Do not open the Code PR page in a browser to learn source/target branch — use gitUrl+branch from the user, plan, or work-item ticket; clone-and-diff computes the merge-base.

All runtime code lives in scripts/ (scripts/detect.ts is the CLI; scripts/validate.ts is the write-back validator).

Trigger routes

Flow

CLI entry: node {baseDir}/scripts/detect.ts --help
({baseDir} is the installed skill folder. Equivalent: $SKILL_DIR/scripts/detect.ts.)

Local data: {baseDir}/data/{taskId}/ (meta, static, context, test cases, plan, writebacks, findings). Each new detection gets a new taskId directory. Do not delete a previous data/{taskId} to start the next run; reuse a directory only when the user continues that same task.

Install (folder or zip — not a JAR)

Unzip so that SKILL.md sits in a folder named defect-detection (must match frontmatter name):

Then: node {baseDir}/scripts/detect.ts get-plan-info --plan-id 1001 --plan-type 2

Pack: bash pack-skill.sh → defect-detection.zip. Do not ship a .jar; hosts load a directory with SKILL.md, not a JVM archive.

Enterprise adapters (no vendor lock-in)

Default local providers store everything under data/platform/ and enterprise/. Switch backends in config.yaml or env vars:

Enterprise HTTP slots (plan / testcase / issues / docs / traces) are defined in scripts/providers/http_slots.ts and documented in references/api/enterprise-http-api.md. Set kind: http plus base_url, or one shared enterprise_http_base_url. Remap a company path with options.paths — no TypeScript change.

export DETECTION_CONFIG=/path/to/config.yaml
# or
export DETECTION_PLATFORM_KIND=http
export DETECTION_PLATFORM_BASE_URL=https://quality.example.com
export DETECTION_TOKEN=...

Call-graph analysis (JVM / Go / Python / C# services, default)

After clone (every non-JS/TS-client repo), detect GitNexus. If it is not installed, run one forced install, then continue analysis. Only if that install fails (and a single --force-install retry still fails) fall back to grep / find.

node {baseDir}/scripts/detect.ts ensure-gitnexus --task-id $TASK_ID --local-dir "$LOCAL_DIR"
# clone-and-diff already calls this for non-JS/TS services. Do not run it again
# unless the clone return has gitnexus.ready=false. Reused clones skip analyze
# when the graph stamp matches HEAD.

Install used: npm install -g gitnexus@latest (or pnpm add -g if npm is missing). Needs Node.js ≥ 18.

Phase 2 STEP B queries the graph when gitnexus.ready=true:

1. Host MCP (impact / context) if the tool list actually has a GitNexus namespace.
2. Otherwise CLI (do not skip to grep while ready=true):

node {baseDir}/scripts/detect.ts gitnexus-impact --task-id $TASK_ID --target Class#method --direction upstream
node {baseDir}/scripts/detect.ts gitnexus-context --task-id $TASK_ID --name Class#method --content

Empty ~/.cursor/mcp.json means MCP is not configured. Optional: gitnexus setup to register it. ready=false → grep / find. Do not block the task. GitNexus is local; it does not talk to a company platform.

bugStatus

0 initial / 2 no defect / 6 suspected / 7 improvement / 3 confirmed fix / 4 invalid / 5 later / 8 duplicate.

AI outputs 6 or 7. Users turn those into 3 / 4 / 5 / 8.

Constraints (short)

• Mission over ceremony: find defects, then self-check before closing.
• No leak: do not show internal field names, commands, or retry noise to the user.
• Write-back only after clone + code-read registration.
• tagId must come from get-tag-list. AST hits must carry ruleId.
• Rank is dual-write: finalize-rank to the platform and record-rank locally.
• Defect content starts with Defect: or Improvement:, includes Lines:X-Y, and a fix/optimize section with a code block.
• Batch write-backs go through batch-update-process. scripts/validate.ts is authoritative.

complete-task does not lock the task. Append or correct on the same taskId. Use retry only when the whole task must be discarded (wrong repo/branch).

Output

Three user-facing moments: start card → milestone cards → final summary.

Final summary must include a report link:

> View full report: [Open]({reportUrl})

reportUrl comes from the platform provider (local HTML file://.../reports/{taskId}.html by default, or your configured report_base_url). If the chat link does not open, open that HTML file in a browser.

The complete-task --summary text is flat plain text (references/output/summary-spec.md): no Markdown tables, because it is stored and rendered by the platform as-is. The chat reply may use tables. In both, split this change vs legacy risk.

Definition of done: coverage/rank gates + complete-task + reconcile-report exit 0 + complete summary with report link.

Errors

• Network / auth: retry; refresh token via the auth provider.
• Format errors: scripts/validate.ts auto-fixes deterministic issues.
• Quality errors: re-analyze, do not tweak wording to pass.
• Clone failure: skip that service, continue others.
• Missing enterprise/plans/{id}.json (or empty HTTP plan): get-plan-info returns degraded=true. Use chat materials (--git, --user-materials-json, add-test-case, add-document). Do not stop.

See references/rules/error-handling.md.