# Issue Spec

> Create or revise a focused specification issue when explicitly requested or required by the repos…

Create or revise a focused specification issue when explicitly requested or required by the repository contribution policy. Discover existing work, capture intent and acceptance criteria, and reconcile decisions before implementation.

- Page: https://ss33.ai/skills/onsager-ai/issue-spec-66914227409
- Publisher: onsager-ai
- Category: [Software Development](https://ss33.ai/skills/category/software-development-t44z8z) › [Source control & code review](https://ss33.ai/skills/category/software-development-t44z8z/source-control-and-code-review-jebezw)
- License: MIT
- Source: https://github.com/onsager-ai/dev-skills/blob/080075df0b75a033aca8f4026fcce710078089da/skills/issue-spec/SKILL.md

## Skill

SKILL.md: https://ss33.ai/api/v1/ss33/download/onsager-ai/issue-spec-66914227409

# 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](../harness-operations/SKILL.md) only if capability mapping
is needed. No personal installation or particular GitHub tool is required.
Read the [format reference](references/spec-format.md) when drafting and use the
[template](templates/issue-spec-template.md) 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](../harness-operations/SKILL.md); 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](../pre-push/SKILL.md) and
   [pr-lifecycle](../pr-lifecycle/SKILL.md). 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](scripts/spec-list.sh) and [show helper](scripts/spec-show.sh)
are optional CLI conveniences requiring authenticated GitHub CLI and jq. Use
connected GitHub tools instead when those prerequisites are unavailable.