issue-spec

Issue specification

Scope

This skill owns specification method, not which changes require a spec. Read AGENTS.md and the relevant repo workflow overlay for the target repository, always-spec surfaces, labels, required sections and exceptions. An explicit request to write a spec is sufficient to start; do not re-ask whether to do it. Use the repository's declared spec medium. Use GitHub issues when it adopts the issue-based SDD loop; do not migrate another repository's spec format by inference.

Prerequisites

Know the intended change, target repo and applicable contract. For GitHub work, use harness-operations only if capability mapping is needed. No personal installation or particular GitHub tool is required. Read the format reference when drafting and use the template as a starting point, not extra policy.

Procedure

1. Discover relevant code, recent changes and existing issues/specs. Reuse or amend related work instead of creating a duplicate. Resolve the target repo from its checkout/remote and contract; do not infer it from the skill's source repo.
2. Capture intent with Overview, Design, independently verifiable Plan items, matching Test items, Alignment and optional Notes. Include the repo's required impact/example sections. Keep the spec near 2000 tokens or less; split a larger feature into a parent and independently scoped children.
3. State boundaries in Alignment. Proceed with already authorized implementation decisions. For a concrete unresolved human boundary needed for the work, use the structured question capability mapped by harness-operations; name its source, affected Plan items, options and tradeoffs. A plain-text question or Human decides checklist alone does not request the decision. Wait for an explicit answer before dependent work; continue independent authorized work. Reconcile the answer into the spec in the same sitting and clear answered blockers. If no permitted question tool exists, state that limitation and use the established handoff channel without assuming an answer.
4. Validate scope, invariants, test coverage, dependencies and required labels. In GitHub bodies keep each prose paragraph or list item on one source line; blank lines separate blocks. Do not mark Plan items complete before delivery.
5. Publish or update the spec through an available authorized tool. Apply existing repo labels, priority and area conventions; do not create a new taxonomy merely because this procedure uses one in an example. Establish child relationships with native sub-issues where supported, otherwise record explicit links.
6. Hand ready work to pre-push and pr-lifecycle. Use the repository's worktree/branch rules. The common procedure does not choose a harness branch prefix.

Completion

Report the spec path/URL, scope, decisions and any blocked publication capability. A local draft is not a published issue. Under issue-based SDD, link final delivery with Closes #N, partial delivery with Part of #N, and reconcile Plan progress only after landing. If the repository has no spec gate, do not impose one.

Optional helpers

The list helper and show helper are optional CLI conveniences requiring authenticated GitHub CLI and jq. Use connected GitHub tools instead when those prerequisites are unavailable.