tars-backlog-create-issue

Files (1)

• SKILL.md

SKILL.md (first lines)

# Backlog Create Issue

This skill defines the canonical structure, format, and content expectations for creating issue tickets in the local backlog. Standardizing this structure ensures coding agents can parse, batch, implement, and review tickets consistently.

## Targets and Paths

- All backlog tickets are stored in the `.tars/issues/todo/` directory relative to the project root.
- File names must follow the format `XXX.md`, where `XXX` is a sequential 3-digit ID (e.g., `001.md`, `002.md`, etc.).
- When creating a new issue, check `.tars/issues/todo/`, `.tars/issues/done/`, `.tars/issues/failed/`, and `.tars/issues/wont-do/` to find the highest existing 3-digit ID. The new file must be named with the next sequential ID (`highest_id + 1`), padded to 3 digits. Do not assume `001` or overwrite existing issue files unless the directories are entirely empty or do not exist.
- `.tars/issues/wont-do/` holds retired and superseded tickets. It is not a failure state, but it **is** terminal: a ticket that depends on one parked there can never be scheduled. Scan it for ID allocation so a retired ID is never reused.
- Ticket files are created locally on disk only. Since `.tars/` must be gitignored, do **NOT** stage, commit, or force-add ticket files to git.

## Canonical Ticket Format

Every backlog ticket must follow this template. **It is meant to be copied verbatim and then edited**, so every value below is a real, valid value rather than a list of alternatives - the permitted alternatives are documented in **Frontmatter field rules** immediately after.

```markdown
---
id: 43
name: "Short descriptive name of the issue"
description: "Detailed description of the issue"
component: "module/name"
priority: "medium"
type: "bug"
estimation: "2h"
# optional; "high" enables the spoke checkpoint protocol
complexity: "normal"
# optional; "high" forces a full implementation review
risk: "normal"
dependencies: []
status: "todo"
attempts: 0
branch: null
batch: null
files:
  - path/to/file1.ts
# optional; path or path#symbol this ticket uniquely owns
owns: []
---

> [!IMPORTANT]
> **`files:` is mandatory and must not be empty.** It is an input to the File rule that decides which tickets may be implemented in parallel - see [tars-backlog-implement](../../engineering/tars-backlog-implement/SKILL.md). A ticket without it cannot be batched with anything and must run alone, so an omitted list silently serialises the backlog at best, and at worst gets treated as "no conflicts" and batched into a collision.
>
> List every file the work will touch, including ones changed only incidentally: test files, fixtures, barrel/index re-exports, lockfiles, and shared append-only files such as a spellcheck dictionary. Under-declaring is the failure that matters; over-declaring only costs a little parallelism.
>
> **`owns:` (optional)** lists modules or exports this ticket is the authority for, as `path` or `path#SymbolName` (e.g. `packages/shared/src/git.ts#CONVENTIONAL_COMMIT_TYPES`). Overlapping `owns:` between tickets serialises them like overlapping `files:`. Use it when two tickets might both add the same constant or edit the same shared implementation even if their `files:` lists look disjoint.
>
> **Soft dependencies:** if ticket B needs an export or behaviour ticket A will introduce, put A in B's `dependencies:` even when the files do not overlap. "Must already be merged" is not the same as "must not collide on disk." Write the edge as an inline array on one line (`dependencies: [12]`) - a multi-line list parses as empty and the edge is lost silently.
>
> **`risk: high`** (security, hooks, auth, shared core) and **`complexity: high`** (large multi-file work) steer review depth and spoke checkpointing during implement - set them honestly.

# XXX - Issue Name

## Description

A comprehensive explanation of the problem, the context in which it occurs, and why the change is necessary. State any known side effects or codebase coordinates.

## Tasks

Detailed list of concrete developer tasks to complete:

- [ ] Task 1 (e.g. Add validation logic)
- [ ] Task 2 (e.g. Write integration test)

## Acceptance Criteria

Explicit, checkable conditions that must be satisfied for the ticket to be considered complete:

- [ ] Criterion 1 (e.g. the project's full test gate passes without error)
- [ ] Criterion 2 (e.g. Invalid input is caught and returns exit code 1)

## Evidence

_(This section starts empty when the ticket is created. It is populated by the implementation agent before completion.)_

Must contain command logs, test runs, or code diffs demonstrating that all Acceptance Criteria are met.

## Review

_(This section is empty when the ticket is created. It is appended by the triage agent during tars-backlog-triage.)_

## Implementation Review

_(This section is empty when the ticket is created. It is appended by the tars-backlog-review agent upon completion of the implementation review.)_
```

## Frontmatter field rules

Ticket frontmatter is read by tooling that must tolerate malformed input in order to report it, so it recognises a **narrow set of shapes**. Anything outside them is not rejected loudly - it is silently misread. Follow these exactly.

| Field          | Required shape                            | What happens when it is wrong                                                     |
| -------------- | ----------------------------------------- | --------------------------------------------------------------------------------- |
| `id`           | bare integer, unquoted, unpadded (`43`)   | -                                                                                 |
| `status`       | quoted string                             | -                                                                                 |
| `batch`        | bare integer or `null` - **never quoted** | a quoted batch cannot be selected when a batch is dispatched by number            |
| `dependencies` | **inline array on one line**: `[1, 2]`    | a multi-line YAML list parses as **empty** - the dependency edges silently vanish |
| `files:`       | block list, items indented **two spaces** | not parsed; the ticket reads as having no files and gets batched into a collision |
| `owns:`        | same block list, or inline `[]`           | not parsed                                                                        |

Permitted values:

- `status`: `"todo"`, `"rework"`, `"done"`, `"failed"`, `"wont-do"`, `"in-review"`.
- `priority`: `"low"`, `"medium"`, `"high"`.
- `type`: `"bug"`, `"feature"`, `"refactor"`, `"security"`.
- `complexity`, `risk`: `"normal"`, `"high"`.

`"wont-do"` marks a retired or superseded ticket (filed under `.tars/issues/wont-do/`); `"in-review"` marks one whose implementation is awaiting review. Both are terminal for scheduling purposes: **a dependency on a ticket in `wont-do/` or `failed/` is an error, not a satisfied edge.**

> [!WARNING]
> **`dependencies:` must be the inline bracketed form.** Write `dependencies: [12, 19]` or `dependencies: []` on one line. This form:
>
> ```yaml
> dependencies:
>   - 12
>   - 19
> ```
>
> reads as **empty**. The ticket then looks unblocked, gets batched alongside the work it depends on, and fails in a way that looks like a code bug rather than a metadata bug.

From MAHDTech/agent-skills, MIT.

More from MAHDTech/agent-skills