# Codebase investigation

- Establish the canonical repository, relevant revision, working changes and applicable project instructions. Preserve unrelated work.
- Derive the relevant surfaces from the question: entry points, callers, data contracts, integrations, configuration, tests and delivery paths. Do not inspect unrelated surfaces just to fill a checklist.
- Trace actual behavior through its owners and consumers. A filename, symbol match or graph edge is a lead; inspect the code needed to support the conclusion.
- For cross-package or cross-service claims, follow the relevant boundary on both sides. Include generated outputs or their generators when they affect behavior.
- Use configured search/graph tools where helpful; account for index freshness, exclusions and dynamic behavior. Confirm decisive claims against current source or runtime evidence.
- Test negative claims with a bounded search and state the searched scope. An absent search result is not proof that behavior cannot exist elsewhere.
- Separate implementation, test intent and observed runtime behavior. Cite paths and revisions where they matter; identify the smallest missing proof rather than assuming success.

# Tool, approach and gap comparisons

- Build the comparison dimensions before judging candidates. Derive them from the user's outcome, current setup and the documented capabilities of named tools; include relevant capabilities the user did not mention.
- Compare candidates against the same material dimensions. For cross-language comparisons, compare what each check detects, not just similar tool or feature names.
- Establish what the current setup actually enables. Separate available, default, opt-in, configured and verified behavior; installing a tool does not enable every feature.
- For a missing capability, check whether an existing tool can provide it before proposing another tool. Assess combined alternatives against the entire capability set they would replace.
- For each material capability, establish scope, configuration, limitations and evidence. Use supported, partial, absent, unknown or not applicable accurately; do not convert unknown to absent.
- When recommending a gate, inspect finding severity, thresholds, exit behavior, scan errors, empty/incomplete scans, exclusions, baseline behavior and supported versions. A report or successful exit alone does not prove enforcement.
- Assess compatibility, execution cost, maintenance and licensing when they could change the choice. Label vendor benchmarks and distinguish them from measurements on the user's workload.
- Search official issue trackers and relevant community discussions for counterexamples and alternatives when reliability matters. User-requested sources such as Reddit must be included; a few posts do not establish community consensus.
- Run a bounded local probe when the decision depends on actual behavior and the task authorizes it. Otherwise state the untested claim and the validation needed; do not present documentation as runtime proof.
- Finish with the recommended set, overlap, remaining gaps and reasons to defer or reject additions. Trace the conclusion back to the original dimensions before saying the set is sufficient.

# External evidence

- Bind the claim to its product, version, date and environment where relevant. Browse for changing facts and whenever the user requests online research.
- Follow specific user-supplied sources and inspect the parts relevant to the decision. Search snippets help locate evidence; inspect the underlying source for decisive claims.
- Prefer official documentation, source, specifications and changelogs for capability and contract claims. Check whether a page describes a released feature, preview or unreleased branch.
- Use issues, Reddit and other community sources to uncover limitations, competing explanations and practical experience. Identify author/vendor claims and anecdotal reports; verify technical conclusions against primary evidence or an authorized probe.
- Check counterevidence when a recommendation or broad claim depends on reliability. Compare the reported environment and version with the user's case before transferring a conclusion.
- Preserve material contradictions. Resolve them using applicability, version and authority; state what remains uncertain when the evidence cannot settle it.
- Cite direct supporting URLs beside material claims, with version/date when it affects the answer. Do not pad the source list or turn an inaccessible page into a guessed fact.

# Library, API and platform contracts

- Identify installed and target versions from manifests, lockfiles and runtime evidence as needed; include endpoint, operating mode and relevant configuration.
- Inspect matching official docs, source and changelogs for the operation in question. Documentation retrieval tools may help locate sources but do not replace checking their version and applicability.
- Check the material contract: accepted inputs, returned values, errors, state changes and configuration. Include authentication, ordering, retries or idempotency only where the operation depends on them.
- Inspect how the repository calls the API and consumes its result. Local types, mocks and old examples can disagree with the current service contract.
- When changing versions or selecting a remedy, inspect the relevant migration notes and known issues. A newer version is not evidence that a particular problem is fixed.
- If local compatibility determines the recommendation, use an authorized minimal parser/compiler/runtime probe. Keep documented support distinct from observed integration behavior.
- If exact-version documentation is unavailable, use relevant source or clearly label the closest evidence and the unresolved compatibility question.

# Failure and remedy research

- Establish expected behavior, observed failure and the exact environment: relevant command/route, input, error, version and configuration. Use available evidence before asking the user to repeat it.
- Reproduce the reported case at its actual failing boundary: command, request, browser/device or runtime. Minimize the case without removing the conditions that trigger it. If reproduction is unavailable, retain that limitation instead of claiming a confirmed cause.
- Form plausible competing explanations and choose the smallest observation that distinguishes them. Investigate the failing boundary and adjacent assumptions rather than repeating the same unsuccessful action.
- Recurrence = comparable symptom, boundary and conditions; a repeated message alone does not prove a shared cause. Compare each attempted change with its result. After repeated failure, require new distinguishing evidence before another similar attempt; otherwise state the missing evidence and next useful check. Reuse the conversation/test evidence, not a separate failure ledger.
- Search current official docs, changelogs and issues using the error and environment. Consult analogous community incidents for leads; match their versions and conditions before adopting a remedy.
- Trace the relevant caller, dependency and response/error handling through Codebase and Library and API routes as needed.
- Tie the correction to a demonstrated mechanism at its owner; a nearby stack frame, correlation or plausible narrative is insufficient. If a candidate fails, reassess the explanation. Keep unresolved hypotheses explicit until evidence distinguishes them.
- If implementation is authorized, verify the original failure and the affected behavior after the correction. Otherwise provide a concrete recommendation and the remaining proof, without implying that a proposed fix has been tested.