| name | rule-research |
| description | Research and scope deslop-js detector ideas before implementation. Use when validating a proposed finding, grounding it in JavaScript/TypeScript/module-system behavior, fixture evidence, false-positive traps, detector precision, or v1 non-goals. |
Rule Research
Use this as stage 1 of the deslop-js detector pipeline.
Pipeline:
rule-research defines the finding contract.rule-writing turns the contract into fixtures, tests, implementation, and public result types.rule-validate verifies signal, noise, compatibility, docs, and release notes.
Do not start implementation until the finding contract is clear. If the user already asked for implementation, make the contract concise and continue.
Interactive Coaching
Ask only for information that blocks a useful contract:
- What code, package, export, dependency, or graph pattern should be reported?
- What makes it actionable dead code, dependency waste, or DRY noise?
- What similar-looking code should stay quiet?
- Is the detector syntax-only, graph-aware, workspace-aware, package-json-aware, or TypeScript-semantic?
- Should v1 skip generated files, config files, dynamic imports, path aliases, type-driven cases, framework conventions, or interprocedural behavior?
When enough is known, present a short finding contract and either ask for confirmation or continue if the user already requested implementation.
Research Workflow
- Define the finding in one sentence:
This detector reports <code/project pattern> because <specific waste, risk, or maintenance problem>.
- Classify the detector surface:
- Source collection and parsing:
packages/deslop-js/src/collect/parse.ts.
- Entry/workspace discovery:
packages/deslop-js/src/collect/entries.ts and packages/deslop-js/src/collect/workspaces.ts.
- Import resolution and graph building:
packages/deslop-js/src/resolver/ and packages/deslop-js/src/linker/.
- Report-stage findings:
packages/deslop-js/src/report/.
- Optional type-aware findings:
packages/deslop-js/src/semantic/.
- Shared AST/project helpers:
packages/deslop-js/src/utils/.
- Inspect existing result shapes in
packages/deslop-js/src/types.ts and exports in packages/deslop-js/src/index.ts.
- Collect evidence:
- JavaScript, TypeScript, Node, package manager, or framework behavior.
- Existing fixtures under
packages/deslop-js/tests/fixtures/.
- Current tests in
packages/deslop-js/tests/analyze.test.ts, semantic.test.ts, type-analysis.test.ts, dependency-utils.test.ts, and errors.test.ts.
- Classify examples:
- Strong positive: exact reportable case.
- Pattern-adjacent: useful but belongs to a different detector.
- False-positive trap: valid or intentional code that must stay quiet.
- Out of scope: too dynamic, framework-specific, type-driven, or expensive for v1.
- Decide detector precision:
- Syntax-only: local AST/source facts are enough.
- Graph-aware: reachability, imports/exports, re-exports, or cycles matter.
- Workspace/package-aware: package.json scripts, workspaces, overrides, dependencies, or entrypoints matter.
- Type-semantic: a TypeScript program/checker is required and the feature belongs behind
semantic.enabled.
- Decide confidence behavior:
- Use
high only when the detector has low ambiguity and a safe suggestion.
- Use
medium or low when intent, API boundaries, framework conventions, or semantic uncertainty remain.
Finding Contract Output
Return this contract at the end of research:
Finding definition:
This detector reports <pattern> because <specific reason>.
Runtime/project reason:
<1-3 sentences>
Detector precision:
Syntax-only | graph-aware | workspace/package-aware | type-semantic
Output shape:
<new or existing ScanResult field, confidence tier, reason/suggestion fields>
Evidence:
- <docs, fixture, issue, or similar-tool evidence>
Strong positives:
- <exact reportable examples>
False-positive traps:
- <valid examples that must stay quiet>
In scope for v1:
- <supported cases>
Out of scope for v1:
- <explicit non-goals>
Test seeds:
- <fixture and assertion ideas>
Open questions:
- <only questions that affect correctness or scope>
Research Rules
- Treat false positives as correctness bugs, especially for
high confidence findings.
- Do not broaden a finding beyond its
reason text or result field contract.
- Prefer explicit non-goals over pretending dynamic project behavior is modeled.
- Keep source-compatible public APIs stable unless the user is intentionally changing them.
- Add a changeset for published package behavior changes when appropriate.
