Feature Context Analysis

Feature Context Analysis

Purpose

Two things go wrong when this phase is skipped.

The agent asks the user questions the code answers, spending the user's attention on facts and then having none left for the decisions only the user can make. Or the agent builds in a style the codebase does not use — a second HTTP client, a third validation approach, an abstraction that already exists two packages away — and the review is about the shape of the code rather than about whether the feature is right.

The output is a context report: findings cite evidence and distinguish observation, inference and unresolved questions. "Not found in this sweep" is bounded search evidence, not proof of absence throughout the system.

Workflow

1. Scope the sweep to the feature. Read what the feature will plausibly touch and one ring around it. A whole-repository survey costs more than it returns and produces a report nobody uses. If the feature is too ambiguous to select relevant paths, ask the smallest scope question; repository investigation does not require delaying a question only the user can answer.
2. Work the checklist in references/investigation-checklist.md — build, dependencies, layering, persistence, messaging, configuration, security, observability, testing, delivery. Relevant concerns get a finding, bounded "not found", "not examined" or "unavailable".
3. Cite everything. path:line, a dependency coordinate with its version, or the command and what it printed. A finding with no citation goes in as an assumption or not at all.
4. Close the unknowns it can close. Walk the discovery ledger and mark each unknown this sweep answered, with the evidence. This is the phase's main product.
5. List reusable components by name and location, with what each would have to change.
6. List the conflicts — anything in the request that the codebase makes awkward, expensive or impossible, and what the code says about why.
7. Label every technology finding as observed, never as required. That distinction is the whole reason the report is trustworthy.
8. Preserve traceability. Assign or reuse F-* for evidence and resolve U-* by appending the fact/source; name the input feature revision so later baseline changes can invalidate findings. Reuse the existing ledger when present; otherwise concise inline IDs/unknowns are enough. Record repository revision and relevant working-tree changes as well as the feature input.

Decision rules

IF a pattern appears repeatedly
THEN report instances, independent contexts, counter-examples and declared/enforced policy.
     Repetition alone does not establish authority or decide this feature's design.

IF a pattern appears once
THEN it is evidence of that instance, possibly the closest relevant precedent;
     explain its scope without generalising it to the whole project.

IF a technology is declared but no direct source use was found
THEN distinguish declared, resolved for the target configuration and observed active use.
     Check configuration, auto-configuration, generated code and reflective loading when relevant;
     absence of imports does not prove it unused or available on the target runtime.

IF no implementation was found in the inspected scope
THEN state paths, search terms and limits; deployment/platform behavior may live elsewhere.
     Report "not found here", not "the project does not need it".

IF the feature needs a capability and something close already exists
THEN name it, say precisely what it lacks, and let the decision phase choose between
     extending it and adding a second one.

IF version-specific API behaviour matters
THEN inspect compiler release/toolchain and resolved dependency evidence for the relevant
     module/profile/configuration, including parents/BOMs/constraints and runtime image.
     If resolution is unavailable, label the declared version and leave behavior conditional.
     Preserve target versions rather than upgrading them to fit an API.

Constraints

• Observation is not authorisation. "The project uses Kafka" is a fact about the project. "This feature will use Kafka" is a decision, and it is not this phase's to make.
• Do not infer a standard from a majority. Consistency across a codebase can mean a standard, a template, or one person who wrote most of it. The report says how many places and whether there is a counter-example; it does not conclude.
• Do not report what you did not read. "The codebase appears to use X" without a path is the failure mode this phase exists to prevent.
• Do not fix anything. Defects found during the sweep are reported, not repaired — they are either in scope, in which case the scope phase adds them, or they are someone else's change.

Output

Existing architecture      <shape, with the paths that show it>
Input revisions            <Product/Engineering or Tech Feature revision IDs>
Relevant modules           <path -> what it owns>
Relevant components        <name, path, what it does>
Existing patterns          <pattern, count, counter-examples>
Existing technologies      <name, version, where used, observed>
Reusable components        <name -> what it would need>
Potential conflicts        <request item vs what the code makes hard, with evidence>
Constraints from the code  <enforced/documented requirement vs change cost, with evidence>
Questions answered         <U-* -> F-*, evidence>
Still unknown              <U-nn, search limits/access gaps, smallest next evidence or question>

Scale the report to the feature: omit irrelevant rows and reuse existing artifacts. Before handing off, verify cited paths match the current revision and each resolved unknown is actually supported. Do not mark a product decision answered merely because one implementation was found.