Unfamiliar codebase?

Find a credible starting boundary before editing

Narrow a capability to a credible source-and-test starting set, then stop if the evidence does not establish ownership.

Starting state

One pinned repository. One concrete goal.

Narrow the investigation without treating a plausible match as permission to edit.

+The developer knows the capability name; its directory and owner are still unknown.
+No DevSpecs task is needed yet; this is repository orientation.
+The local index contains source context, tests, docs, and Git receipts.

Repository: fastapi/fastapi
Commit: 3d2aace4
DevSpecs: v1.3

DevSpecs entry

$ds map "Custom Response"

DeveloperDevSpecsCoding agent

Workflow

STEP 1 OF 4

Ask for a starting boundary

Developer

Start from a capability name and let the map suggest a bounded area before searching individual files.

Command

$ds map "Custom Response" --no-refresh

CLI output

Custom Response · high confidence

Purposeowns domain feature behavior for Custom Response

Boundarydocs_src/custom_response/**

Boundarytests/test_tutorial/test_custom_response/**

Tryds find "custom response"

What this tells you

The map identifies a credible docs-plus-tests boundary. One broader adjacent candidate also appears, so ownership still needs inspection.

Continue with

Use the map-provided query to inspect concrete evidence.

Output verified against the pinned run

This receipt is the capture file used to check the excerpt. You do not need it to follow the workflow.

Normalized scoped map JSON · 22-map-custom-response.stdout.txt

STEP 2 OF 4

Narrow to concrete artifacts

DevSpecs

Search inside the question and keep inclusion, exclusion, and Git receipt signals alongside the filenames.

Command

$ds find "custom response" --no-refresh

CLI output

Included4 · excluded noise: 4

Topdocs_src/custom_response/tutorial004_py310.py

Alsodocs_src/custom_response/tutorial009c_py310.py

Warningno primary implementation surface is visible

Noiseunrelated current task artifacts also matched `custom`

What this tells you

The query reaches real examples. A primary implementation file remains unresolved, and current task artifacts matter only when the question overlaps them.

Continue with

Choose one real source-context result and inspect it exactly before deciding what else to open.

Output verified against the pinned run

This receipt is the capture file used to check the excerpt. You do not need it to follow the workflow.

Normalized custom-response find JSON · 23-find-custom-response.stdout.txt

STEP 3 OF 4

Open the exact artifact

DevSpecs

Use the short ID from the find result to export the indexed body without another ranking pass.

Command

$ds context 2c3f9948 --no-refresh

CLI output

source_pathdocs_src/custom_response/tutorial004_py310.py

kindsource_context

importsFastAPI, HTMLResponse

definesgenerate_html_response(), GET /items/

What this tells you

This concrete custom HTML response example shows how the capability is used. Framework ownership still needs verification.

Continue with

Follow the mapped test boundary or imported FastAPI response type before proposing an edit.

Output verified against the pinned run

This receipt is the capture file used to check the excerpt. You do not need it to follow the workflow.

Normalized short-ID context JSON · 24-context-custom-response.stdout.txt

STEP 4 OF 4

Decide whether a task is warranted

Developer

Stop the orientation pass once the boundary and one exact artifact are understood. Create a task only when the intended change is clear.

What this tells you

The docs example and tutorial tests form a useful starting set, but the primary implementation surface remains unresolved.

Continue with

Inspect the imported response implementation for a framework change, or stay within docs/tests for an example-only change.

Result

The developer narrowed the investigation to a high-confidence docs/test boundary and one inspectable source example. No primary implementation owner was established, so the workflow stopped without authorizing an edit or creating an unnecessary task.

Common failure

Treating routing output as ownership proof

A plausible result is evidence, not ownership proof. The real find receipt warns that no primary implementation surface is visible, and unrelated active task artifacts also match the broad word `custom`.

Use context to inspect exact candidates, then verify imports, owner docs, and tests. Source and maintained documentation remain authoritative.