issue-spec

Draft issue specifications with problem, approach, and acceptance criteria.

1|Updated Apr 28, 2026

Search Tags:#planning #specification #journal #acceptance-criteria #issue-spec #tracker #convoy-spec

Ready to run

npx skills add https://github.com/naramore/dotai --skill issue-spec

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: issue-spec
Source: https://github.com/naramore/dotai/tree/main/claude/skills/issue-spec
Command: npx skills add https://github.com/naramore/dotai --skill issue-spec

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Drafting precise and consistent issue specifications across trackers (Beads, Linear, GitHub Issues, Jira) to reduce ambiguity and rework.

Core Features & Use Cases

Standardized templates for Problem, Approach, Files to Create/Modify, Content Source, Acceptance Criteria, Out of Scope, and Test Plan.
Back-end agnostic guidance and sections to support drafting, reviewing, and auditing issues across platforms (Beads/Linear and mirrors).
Works for per-item work items and supports convoy-spec when part of a convoy.

Quick Start

Draft a complete issue spec using the template described in this skill for a new feature or task.

Frequently Asked Questions about issue-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I draft precise issue specifications for work items across different trackers?▼

To draft precise issue specifications, use a standardized template covering the problem, approach, files to modify, acceptance criteria, out of scope, and test plan. This backend-agnostic approach reduces ambiguity and rework across trackers like Beads, Linear, GitHub Issues, and Jira.

What sections should be included in an issue specification template?▼

An effective issue specification template includes Problem, Approach, Files to Create/Modify, Content Source, Acceptance Criteria, Out of Scope, and Test Plan sections. It requires minimal frontmatter with a name and description to support drafting and auditing issues across platforms.

Can I use this issue specification format with Linear and Beads trackers?▼

Yes, this issue specification format works with Linear and Beads. It provides backend-agnostic guidance with sections to reference related documentation and storage backends specifically for Beads and Linear, ensuring consistent issue drafting across platforms.

How do I manage parent-child task specifications in a convoy workflow?▼

To manage parent-child task specifications in a convoy workflow, use the convoy-spec support. This allows you to draft per-item work item specs while maintaining hierarchical relationships, ensuring all child tasks align with the parent issue's approach and acceptance criteria.

Why do I need acceptance criteria and a test plan in my issue specs?▼

Acceptance criteria and a test plan are needed in issue specs to reduce ambiguity and prevent rework. They define clear completion standards and verification steps, ensuring the implemented approach solves the stated problem and meets quality expectations before closing the issue.

Does this issue specification template require any specific tracker dependencies?▼

No, this issue specification template is backend-agnostic and has zero dependencies. It prescribes a minimal frontmatter requirement of just a name and description, allowing you to draft and audit issues across any tracker without installing specific platform integrations.