issue-contract-expansion

name	issue-contract-expansion
description	Turn a concrete GitHub issue ask into repo-truth + implementation when the requirement is additive but the contract is not documented yet.

Issue Contract Expansion

When to Use

• A GitHub issue asks for a concrete additive feature, surface, or workflow
• Current repo docs do not yet describe the contract, but the ask is still landable
• The session can update repo truth and the bounded implementation together

Canonical Surfaces

• GitHub issue thread comments via ./.git/helpers/gh-app
• AGENTS.md
• README.md
• The owner doc for the touched surface under docs/ or research/
• The code or data files that implement the issue ask

Procedure

1. Read the full issue, latest comments, and the current owner doc for the affected surface
2. Decide whether the ask is additive and safe on current main, or whether it truly needs escalation
3. Use mapped only for brief decomposition, then move into active or writing once the path is clear
4. Update the owner doc, AGENTS.md, and any relevant skill in the same slice when repo truth is missing
5. Land the bounded implementation that matches the new repo truth; keep docs, code, and data aligned
6. Use validation-ready and closeout only after the shipped result rechecks clean on current main

Guardrails

• Missing contract text alone is not a blocker
• Reserve blocked for external dependencies, unsafe ambiguity, or a direct policy conflict that cannot be resolved in the same slice
• Do not ship placeholder UI, synthetic data, or screenshot-only hacks just to avoid saying no
• Keep issue comments concrete and user-surface-focused

Validation

• The same slice updates repo truth and the implementing files
• The issue thread reflects active or writing, not a blocker-only note, when the ask is additive
• Closeout uses .agents/skills/issue-watch-closeout/SKILL.md after the result ships