Investigate an unfamiliar repository

This workflow produces a map of one request path, not a speculative description of every module. Use it when joining a project or evaluating a change to an unfamiliar subsystem.

1. Establish the baseline

You need a local checkout, authenticated agent, and the project's documented development environment. Record existing modifications before starting. If the project provides Git in its flake:

nix develop -c git status --short
nix develop -c git rev-parse HEAD
agent-cli --cwd /absolute/path/to/project

Replace the path with the checkout you inspected. If its flake has a named shell, use that shell for the Git commands. Do not create new instructions with /init yet: first understand the conventions already present in AGENTS.md and the README.

2. Trace one operation

Choose an operation the project actually implements, such as session search. Substitute your operation in this request:

Investigate how session search works. Do not edit files or install dependencies.
Find the user entry point, request parsing, query implementation, result ordering,
and tests. Cite file paths and line numbers for each link in the chain.
Separate confirmed behavior from assumptions. List the documented test command,
but do not run it until you have explained its environment and side effects.

Open the cited files yourself. A useful result connects specific functions and tests; a list of directories alone is not sufficient. Ask for missing links:

Show the call site that connects the command handler to the search function. Which test proves the ordering claim?

3. Check the evidence

Once you understand the test command, authorize the focused check. Prefer the repository's established workflow; for this Haskell repository, that means GHCi in the Nix shell rather than rebuilding the whole application for an exploratory check.

Run the focused tests using the repository instructions. Report the exact command, result, and any environment failure separately from application failures. Do not change files to make the environment pass.

If a test requires credentials, writes to a database, or contacts a service, inspect that requirement before allowing it. A read-only investigation request is guidance to the model, not an operating-system sandbox.

4. Turn findings into a bounded plan

/plan Propose a change to session search that preserves current ordering and empty-query behavior. Identify the files to change and regression tests. Do not implement yet.

/view-plan displays the saved proposal. Plan mode restricts edits to the session plan file; the preceding investigation was an ordinary conversation. Reject assumptions not supported by code or requirements. Approve implementation only after the proposal states observable acceptance criteria.

5. Retain and resume the investigation

/rename Session search investigation
/session
/export /absolute/path/to/private-investigation.md

Choose an actual private export path. Review the export before sharing because it may contain source excerpts and tool results. Use /quit to leave without deleting the conversation; later use agent-cli --resume SESSION_ID.

Recheck Git status at the end. Explain any difference from the baseline before treating the investigation as read-only. If a citation does not exist, ask the agent to reread the file and correct its report rather than carrying the assumption into implementation.