Repo Map First

Place Changes with Repository Evidence

Resolve where a change belongs before implementing it when placement mistakes could cross responsibilities or spread through the wrong layer. Keep repository maps evidence-based and update them only when the task or an explicit request justifies the documentation work.

Select the Invocation Mode

Explicit Map Mode

Use this mode whenever the user names this skill or asks to create, repair, update, inspect, or use repository map documents.

The requested action determines the scope; naming the skill does not itself authorize document changes.

• Inspect or use: read relevant existing maps, verify task-relevant claims against source, and report ownership, discrepancies, and limitations. Resolve missing information from source when possible. Missing or stale maps do not turn inspection into a creation or repair task.
• Create, repair, or update: inspect existing maps and source, then create missing documents or repair stale relevant sections within the requested scope. When the user requests repository maps without naming documents, cover both docs/REPO_MAP.md and docs/ARCHITECTURE.md; a request for one document does not require creating its companion. Leave accurate sections unchanged.
• Complete the requested map work before any dependent implementation. A map-only request ends with the map result and its evidence; it does not authorize code changes.

Map work is sufficient when the requested owners, entry points, flows, and dependencies are locatable and evidence-backed, with material unknowns explicit. Inspection may report an unresolved gap without modifying documents. Creation and repair must produce the requested artifacts or explain which missing evidence prevents that.

Automatic Placement-Risk Mode

Use this mode only when an existing-repository behavior change has a real placement risk, such as:

• responsibility ownership or the implementation location remains unclear from the request and known context;
• the change crosses module or layer boundaries;
• entry points, dependency direction, public contracts, or key call flows may change;
• the repository is unfamiliar and the work is non-local;
• a relevant map appears missing, stale, contradictory, or insufficient for a cross-boundary decision.

Cross-file work alone is not enough. A local, well-specified change within one clear responsibility does not need this skill.

If brief inspection shows that placement is clear, no boundary is crossed, and no durable structure changes, release this skill and continue through the normal implementation workflow without placement analysis or map creation.

When maps are absent in automatic mode, resolve placement from the relevant source first. Create or repair repository documents only when they are necessary for safe placement or the task will change durable repository structure.

Repository-Context Bootstrap

Use this mode only when another skill explicitly requests repository context because docs/REPO_MAP.md or docs/ARCHITECTURE.md is missing.

1. Identify which documents are missing and preserve any existing companion document.
2. Read applicable repository rules and existing documentation.
3. Inspect the repository with rg --files, rg, and targeted reads. Locate manifests, workspaces, entry points, relevant modules, public contracts, callers, dependencies, and tests.
4. Preserve the dependent skill's target artifact.
5. Create only the missing documents and begin each generated file with:

---
generated_by: repo-map-first
authority_status: observed
---

6. Include only claims supported by repository evidence. Mark unknown relationships as unknown.
7. If the repository lacks enough evidence for the minimum content below, report INSUFFICIENT_INPUT instead of creating a misleading map.

The minimum REPO_MAP.md content is:

• Relevant top-level directories and modules
• One-sentence responsibility for each relevant module
• Primary entry points
• Key call chains or flows
• Locations of public contracts and tests used as evidence

The minimum ARCHITECTURE.md content is:

• Observed layers or module boundaries
• Observed dependency direction
• Main control or data flows
• Ownership of important state or data
• External systems and operational boundaries when present

Return control to the dependent skill after the requested documents exist. Generated documents remain observed context until the user explicitly changes authority_status to confirmed.

Repository-Context Validation

Use this mode only when another skill explicitly requests validation because a recently completed predecessor or repository evidence makes existing docs/REPO_MAP.md or docs/ARCHITECTURE.md claims potentially stale for the dependent task.

1. Preserve the dependent skill's target artifact.
2. Read the existing map documents and staleness-checklist.md.
3. Inspect only the source, entry points, owners, dependencies, flows, and tests needed to validate the relevant scope.
4. Leave accurate map sections unchanged. Repair only stale relevant claims in authority_status: observed documents and preserve their provenance.
5. Do not rewrite an unmarked or authority_status: confirmed contract from observed code. Report the contradiction and return INSUFFICIENT_INPUT when the dependent workflow requires the conflict to be resolved.
6. Report the evidence checked, any repaired claims, and remaining limitations, then return control to the dependent skill.

Keep These Boundaries

• Begin implementation only after responsibility ownership and code placement are materially resolved.
• Verify stale or contradictory map claims against the relevant source and current behavior.
• In explicit map mode, complete the requested map work before implementation.
• Reuse existing modules, boundaries, and extension points; introduce a layer only when the requested behavior establishes a durable responsibility.
• Keep refactoring to boundary corrections required by the requested behavior. Explain the root cause and make the smallest justified correction.
• Preserve generated_by and authority_status provenance unless the user explicitly confirms a different authority status.
• Keep a dependent skill's target artifact unchanged during repository-context bootstrap or validation.

Placement Workflow

Use this workflow for implementation with unresolved placement risk. Explicit map-only work, repository-context bootstrap, and repository-context validation follow their scoped workflows above.

1. Read applicable repository rules and inspect enough source to locate the current entry point, owner, call flow, and dependency direction.
2. Read the relevant portions of docs/REPO_MAP.md and then docs/ARCHITECTURE.md when present.
3. Use staleness-checklist.md to decide whether the maps are trustworthy and what the current invocation mode requires.
4. State the placement decision using placement-analysis.md as a quality rubric, not a fixed template. Keep it brief unless the task crosses several independent subsystems or has high placement uncertainty.
5. Make the smallest viable change within the resolved responsibility boundary.
6. Use map-sync-checklist.md after implementation. Update REPO_MAP.md when responsibilities, files, entry points, or flows changed; also update ARCHITECTURE.md when layers, dependencies, or cross-system relationships changed.
7. Report whether responsibilities, entry points, or key flows changed and whether map documents were synchronized.

Working Principles

• Prefer repository evidence over remembered or intended architecture.
• Discover context before asking generic placement questions.
• Use the least map detail needed to place the current change safely.
• Keep explicit user control stronger than automatic routing judgment.
• Distinguish responsibility boundaries from file count.
• Keep placement analysis concise and implementation-focused.