‘Can we replace our authentication provider?’ is a decision question. Giving it straight to an editing agent can produce an impressive diff before the team has agreed on migration risk. Research first when the unknowns matter.
Decide how much answer you need
For ‘where is login handled?’, a quick orientation answer may be enough. For ‘what breaks if we replace this provider?’, request a research job with cited files, tests, configuration, data migration paths, and open questions. Only ask for a code-changing task after someone can state the desired outcome and constraints. Canopy's current-main documentation distinguishes one Companion for cross-project answers, research jobs that preserve findings without changing code, and background tasks that can deliver code through a draft PR. Confirm these surfaces in your installed release.
Ask for evidence, not a verdict
A useful research request names the decision, the repository scope, and the output format. Ask the investigator to separate observed facts from inferences: file paths and symbols for implementation, test names for current behavior, configuration or deployment assumptions, and external documentation for provider behavior. If a claim cannot be verified from the checkout or a primary source, label it unknown. This prevents a polished summary from hiding the one assumption that would make a migration fail.
Keep the work read-only while deciding
State ‘do not edit files, install packages, rotate credentials, or change remote state’ in the request. Check the changed-file view afterward to verify that the investigation stayed within scope. Canopy documents research jobs as preserving findings and sources without changing code; a regular CLI session still follows the permissions and behavior of that CLI, so give it an explicit read-only scope if you use one for research.
Make a decision record people can resume
Summarize the options, evidence, trade-offs, unknowns, and recommended next experiment in a project note or ticket. Link the research result and exact source files instead of pasting an entire conversation. SpotSearch can retrieve notes, research, tickets, and past conversations according to Canopy's current-main documentation, but the decision record should stand on its own when someone returns later or switches CLIs.
Convert the decision into a small implementation
If the team chooses to proceed, split the migration into reversible steps. For example, first add an adapter around the current auth calls with tests; then migrate one low-risk path; then plan data and rollback. Give the implementation agent one step, an isolated checkout, acceptance checks, and a PR to review. Keep the research result linked so a reviewer can test whether the change follows the agreed constraints.
Copyable resources
Copyable read-only research request
Use when a change needs a decision before code.
Decision: Can we replace [current system] with [candidate] safely?
Scope: [repository and affected flows]
Do not edit files, install packages, change credentials, or modify remote state.
Find: current entry points, data contracts, tests, deployment assumptions, and migration or rollback risks.
For each finding: cite file/path or primary source; mark observation versus inference; state confidence and unknowns.
Output: one-page option comparison, smallest useful experiment, and questions a human must decide.
Afterward: save the result with a link to the ticket or project note.Frequently asked questions
When is a Companion answer enough?
Use it for a quick orientation or status question. Use a source-backed research job when the answer will drive a costly or hard-to-reverse change.
Will research start editing my repository?
Canopy's current-main documentation describes research jobs as preserving findings without changing code. If you investigate through a normal CLI session, give it an explicit read-only scope and inspect the changed-file view afterward.