Backlog Task Template

Backlog Task Template

Copy the block below into docs/backlogs/<KIND>-YYMMDD-xx.md. Fill each section. Readable in under a minute. Same philosophy as the [[adr/template|ADR template]]: frontmatter is metadata for Obsidian Bases + the graph; the body is a tight, scannable record. Unlike an Accepted ADR, a task card is mutable — it moves through a status lifecycle.

Three kinds, one backlog

All cards live here and are identical in everything but the filename prefix (and the matching kind field/tag):

Kind	Filename	What it is
ISSUE	ISSUE-YYMMDD-xx.md	Something to fix — bug, defect, chore, debt.
FEATURE	FEATURE-YYMMDD-xx.md	New functionality to build.
IDEA	IDEA-YYMMDD-xx.md	A proposal / exploration / spike — not yet committed work.

Filenames are coded, never descriptive — no slugs, no “weird names”. The topic, area and relations are carried by title, Obsidian tags, and wikilinks inside the card.

---
id: ISSUE-YYMMDD-xx       # mirrors the filename stem (UPPERCASE prefix)
title: "[One-line statement — this is where the human-readable name lives]"
kind: issue               # issue | feature | idea  — matches the filename prefix and the tag below
status: backlog           # backlog | todo | in-progress | blocked | done
priority: medium          # low | medium | high | critical
area: ""                  # auth | employees | org-units | positions | assignments | hours | coverage | business-rules | tags | audit-log | frontend | backend | infra | design-system | docs | agents
created: YYYY-MM-DD
updated: YYYY-MM-DD
related:                  # [[wikilinks]] to VAULT NOTES in play — ADRs, PRD, API, sibling cards (graph edges). Omit if none.
  - "[[adr-NNN-slug]]"
  - "[[ISSUE-YYMMDD-xx]]"
paths:                    # repo files/globs this card TOUCHES — code lives outside the vault, so track it here (paths, not wikilinks). Omit if none.
  - "backend/path/to/file.py"
  - "frontend/src/app/feature/**"
tags: [backlog, issue]    # backlog + the kind; add area/topic/bug tags freely — "tags for everything"
---
# ISSUE-YYMMDD-xx — [Title]

## Contexto

What's wrong / what's wanted, and why it matters. Link the PRD principle, API contract, or ADR in
play with a `[[wikilink]]`. Enough for someone cold to act without asking a follow-up.

## Criterios de aceptación

- [ ] A concrete, checkable outcome.
- [ ] Another one. **Done = every box ticked.**

## Notas

Investigation notes, evidence (`file:line`, log excerpts), options weighed, decisions taken.
Append-only as the card moves through its lifecycle.

For a FEATURE or IDEA, change only the filename prefix, the id prefix, the kind value, the H1, and the kind tag — everything else is the same shape.

Frontmatter keys

Keep every key present (leave empty rather than dropping it) so Bases can filter without holes.

Key	Meaning
id	<KIND>-YYMMDD-xx — mirrors the filename stem. UPPERCASE prefix; lets Bases sort.
title	One-line statement — the human-readable name lives here, not in the filename. Quote it. Drives the graph node label.
kind	issue | feature | idea — the card’s bucket; matches the filename prefix and the kind tag.
status	Lifecycle: backlog → todo → in-progress → done, with blocked as a side state.
priority	low | medium | high | critical.
area	The project surface it touches — one value from the suggested set (mirrors ADR domain + app modules).
created / updated	ISO YYYY-MM-DD. Bump updated on every edit.
related	[[wikilinks]] to vault notes — the ADR/PRD/API sections and sibling cards it implicates. These resolve as backlinks/graph edges. Omit the key when empty.
paths	The repo files/globs this card touches — code, configs, anything outside the docs/ vault that can’t be wikilinked. Mirrors the ADR paths key, so a Base can answer “what open work touches this file?”. Omit the key when empty.
tags	backlog + the kind (issue/feature/idea); add area/topic tags freely (e.g. bug). Tags are how the backlog is sliced.

[!tip] related vs paths — the two ways a card connects related points at notes inside the vault (ADRs, PRD, API, sibling cards) → real [[wikilinks]], so they appear as backlinks and graph edges. paths points at repo files outside the vault (code, configs) → plain path strings or globs, so Bases can group cards by the file they touch — the same way ADRs scope rules. A card may carry both: the spec it references in related, the code it fixes in paths.

Kinds map cleanly: a bug is kind: issue + a bug tag; a suggestion is kind: idea.

Naming & lifecycle

• File: <KIND>-YYMMDD-xx.md — KIND ∈ ISSUE/FEATURE/IDEA; YYMMDD = 2-digit year-month-day of created; xx = 2-digit counter per kind, per day (each KIND+date starts at 01).
• Wikilink target is the bare filename, e.g. [[ISSUE-260531-01]].
• Register the new card in [[backlogs/README|docs/backlogs/README.md]] at creation time (Index table) — same discipline as adding an ADR to its README.
• Cards are mutable, not immutable: a card evolves; a done card is kept as history, never deleted (consistent with the non-destructive ethos, PRD §7.4).
• When a card’s resolution is a genuine architectural decision, draft a new ADR from [[adr/template]] (status Draft) and link it in related — an ADR only becomes Accepted with express user confirmation.

[!example] Worked example See the canonical filled card — the health-endpoint 429, ISSUE-260531-01 — embedded in the cotton-coveris-backlog agent and (once seeded) in this folder.