repo-map-first

用仓库证据决定变更位置

当放错位置可能跨越职责边界，或让影响扩散到错误层级时，先确定变更属于哪里，再实施。让仓库地图以证据为基础；只有任务或明确请求证明文档工作合理时才更新它。

选择调用模式

明确地图模式

用户点名本技能，或要求创建、修复、更新、检查或使用仓库地图文档时，一律使用此模式。

请求的动作决定范围；点名技能本身不授权修改文档。

• 检查或使用： 阅读相关现有地图，用源代码验证与任务有关的说法，并报告归属、差异和限制。尽可能从源代码补齐缺失信息。地图缺失或过时不会把检查变成创建或修复任务。
• 创建、修复或更新： 检查现有地图和源代码，然后在请求范围内创建缺失文档或修复过时的相关部分。用户要求仓库地图但未点名文档时，同时覆盖 docs/REPO_MAP.md 和 docs/ARCHITECTURE.md；请求其中一个并不要求创建另一个。准确部分保持不变。
• 在任何依赖实施前完成被请求的地图工作。只要求地图的任务以地图结果和证据结束，不授权代码修改。

当所需的所有者、入口、流程和依赖都可定位且有证据支持，并已说明重要未知项时，地图工作即足够。检查可以报告未解决缺口而不修改文档。创建和修复必须生成所请求的产物，或说明哪些缺失证据阻止了完成。

自动位置风险模式

只有既有仓库的行为变更存在真实位置风险时才使用此模式，例如：

• 从请求和已知上下文仍无法确定职责归属或实现位置；
• 变更跨越模块或层级边界；
• 入口、依赖方向、公开契约或关键调用流程可能改变；
• 仓库陌生且工作并非局部修改；
• 相关地图似乎缺失、过时、矛盾，或不足以支持跨边界决定。

跨多个文件本身不够。职责清晰范围内的局部、规格明确变更不需要本技能。

如果简短检查表明放置位置清晰、没有跨越边界且没有持久结构变更，停止使用本技能，按正常实施流程继续，不做位置分析或创建地图。

自动模式下缺少地图时，先从相关源代码确定位置。只有安全放置所必需，或任务会改变持久仓库结构时，才创建或修复仓库文档。

仓库上下文初始化

只有另一项技能因 docs/REPO_MAP.md 或 docs/ARCHITECTURE.md 缺失而明确需要仓库上下文时，才使用此模式。

1. 确定缺失的文档，并保留现有配套文档。
2. 阅读适用的仓库规则和已有文档。
3. 使用 rg --files、rg 和定向阅读检查仓库，定位清单、工作区、入口、相关模块、公开契约、调用方、依赖和测试。
4. 保留依赖技能的目标产物。
5. 只创建缺失文档，并在每个生成文件开头写入：

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

1. 只包含有仓库证据支持的说法，未知关系标记为未知。
2. 仓库证据不足以满足下列最小内容时，报告 INSUFFICIENT_INPUT，不要创建误导性的地图。

REPO_MAP.md 的最小内容：

• 相关顶层目录和模块；
• 每个相关模块的一句话职责；
• 主要入口；
• 关键调用链或流程；
• 作为证据使用的公开契约和测试位置。

ARCHITECTURE.md 的最小内容：

• 观察到的层级或模块边界；
• 观察到的依赖方向；
• 主要控制或数据流程；
• 重要状态或数据的归属；
• 存在时的外部系统和运行边界。

所需文档存在后，把控制权交回依赖技能。生成文档始终只是观察到的上下文，直到用户明确将 authority_status 改为 confirmed。

仓库上下文验证

只有另一项技能因刚完成的前置任务，或仓库证据表明现有 docs/REPO_MAP.md 或 docs/ARCHITECTURE.md 对依赖任务可能过时时，才使用此模式。

1. 保留依赖技能的目标产物。
2. 阅读现有地图和 仓库地图时效性检查清单。
3. 只检查验证相关范围所需的源代码、入口、所有者、依赖、流程和测试。
4. 准确的地图部分保持不变。只修复 authority_status: observed 文档中已过时的相关说法，并保留其来源信息。
5. 不要根据观察到的代码改写未标记或 authority_status: confirmed 的契约。报告矛盾；依赖流程需要解决冲突时，返回 INSUFFICIENT_INPUT。
6. 报告检查的证据、修复的说法和剩余限制，然后把控制权交回依赖技能。

保持这些边界

• 只有职责归属和代码放置已得到实质解决后才开始实施。
• 用相关源代码和当前行为验证过时或矛盾的地图说法。
• 在明确地图模式中，实施前完成被请求的地图工作。
• 复用已有模块、边界和扩展点；只有请求的行为确立了长期职责时才引入新层。
• 重构仅限于请求行为需要的边界修正。说明根因，并做最小且有理由的修正。
• 除非用户明确确认不同的权威状态，否则保留 generated_by 和 authority_status 的来源信息。
• 仓库上下文初始化或验证期间，保持依赖技能的目标产物不变。