jungho-git/surface

Surface

• Shared examples and formatting reference: references/EXAMPLE.md.
• Keep new guidance, snippets, and edits aligned with that file.

---

Scope

Use this rule when:

• locating the entry point for a requested change
• assessing blast radius before implementation or review
• checking coupled callers, DTOs, mappers, schemas, configs, generated artifacts, or command arguments
• deciding which files are in scope and which are follow-up only
• current project context may depend on sibling projects or shared contracts

Surface analysis should find the nearest implementation boundary, not map the whole repository.

---

Exploration Order

• Start from the requested file, symptom, command, route, table, or entry point.
• Identify direct callers, consumers, tests, fixtures, and generated artifacts.
• Trace immediate dependencies and outputs.
• Inspect contract edges that the change can break.
• Inspect data/schema/config/deployment edges when persistence or runtime behavior is touched.
• Inspect sibling repositories or shared libraries only when current project evidence points there or the user provided them as scope.
• Stop when the implementation surface and required coupled updates are clear enough.

Exploration should produce a bounded edit map.

---

Surface Map

Capture only evidence that affects scope:

• entry point
• direct callers and consumers
• dependencies and outputs
• contract edges
• data/schema edges
• config, environment, deployment, or feature flag edges
• generated artifacts and source generators
• in-scope files
• out-of-scope files
• open questions or blockers

Separate confirmed in-scope files from possible follow-ups.

---

Contract Edges

Check relevant edges such as:

• method signatures and overloads
• DTO, payload, event, or response shapes
• mapper parameters and query result shapes
• table columns, DDL, constraints, indexes, nullability, and defaults
• props, returned data, and UI state assumptions
• config keys, feature flags, environment variables, and secrets references
• CLI arguments, file path conventions, and generated file locations
• serialization formats, versioning, and backward compatibility

Do not treat changed code alone as the full contract.

---

Stop And Expand Rules

• Stop when direct callers, contracts, and required coupled files are clear.
• Expand when a signature crosses module boundaries.
• Expand when persistence, API contracts, generated artifacts, auth, deployment, or scheduled jobs are involved.
• Expand when tests or call sites show behavior differs from the obvious local path.
• Do not expand only because unrelated architecture looks interesting.

Expansion requires evidence.

---

Handoff Shape

• changed surface
• required files
• coupled checks
• files intentionally left out
• assumptions and blockers
• minimum validation path

Use this handoff before implementation or review findings.

---

Boundaries

• Do not map the whole repository without evidence.
• Do not turn surface analysis into a redesign plan.
• Do not keep reading distant modules once the contract surface is understood.
• Do not use generated, cached, vendor, or build output as source-of-truth when canonical source exists.
• Do not hide uncertainty; mark it as an assumption, blocker, or follow-up boundary.