| name | backlog-writer |
| description | Guides authoring of a new spec document. Ensures every required section is present and meets minimum quality before the item enters the gate pipeline. Does not validate gates or make approval decisions. |
Backlog Writer
Content authoring guide for spec documents. This skill produces a correctly structured spec document file ready for GATE-WRITE. It does not run gates, judge gate outcomes, or make implementation decisions.
Rule Anchor
.agents/rules/spec-workflow.md > HARD GATE: No Immediate Implementationbacklog-pipeline skill > State Machine
When to Use
Invoked by backlog-pipeline when a new spec document needs to be created. Also usable directly when drafting a spec document outside the pipeline.
New vs Existing Items
New item: Create .agents/spec-docs/draft/<ID>.md from the schema below.
Existing item (migration): If a file already exists but uses an old schema (no frontmatter, no ## Test Plan, no ## Evidence Log):
- Read the existing file.
- Extract existing content and map to new sections.
- Overwrite with the full new schema, preserving extracted content.
- Set frontmatter
status: draft — must pass GATE-WRITE before upgrading.
- Existing Acceptance Criteria → map to
## Completion Criteria, add TC-N IDs, rewrite to meet quality bar.
Output
A .agents/spec-docs/draft/<ID>.md file with frontmatter status: draft, containing all required sections.
Spec Document File Schema
Create or rewrite the file at .agents/spec-docs/draft/<ID>.md using this exact structure:
---
status: draft
type: <one of 11 prefixes — see taxonomy below>
tags: [<tag>, <tag>]
---
# <ID>: <Title>
## Problem
<!-- symptom + reproduction condition -->
## Prior Art Research
<!-- DEFAULT-ON (research.md). Comparable commercial products / OSS / AI-agent references from PRODUCT DOCS
(not source code): observed common behavior + the constraint that applies to Robota, with ≥1 doc citation
(http link) OR an explicit "no comparable reference found". This feeds Alternatives + Decision below.
Opt out ONLY with an explicit `Waived: <reason>` line (agent-proposed or user-requested). Enforced by
scan-spec-research.mjs + GATE-WRITE. -->
## Architecture Review
### Affected Scope
### Alternatives Considered
### Decision
### Architecture Review Checklist
- [ ] 영향 패키지/레이어 목록 작성 완료
- [ ] Sibling scan 완료 — 또는 N/A: <명시적 이유>
- [ ] 대안 최소 2개 검토 완료
- [ ] 결정 근거 문서화 완료
## Fallback & Degradation Declaration
<!-- HARNESS-028. Default "None". Declare EVERY intentional fallback / graceful-degradation / silent
catch→default this change introduces, and justify each (why it is sanctioned, not a hidden
alternative path). The No Fallback Policy (operational.md) forbids silent fallbacks; a DECLARED +
justified one is reviewed at GATE-APPROVAL by proposal-reviewer. The mechanical floor
(scan-no-fallback.mjs) also requires each sanctioned site to carry `// allow-fallback: <reason>`
in code. If this change adds none, write exactly "None". -->
None
## Solution
## Affected Files
## Completion Criteria
<!-- TC-N prefix required on every item -->
- [ ] TC-01: <criterion>
- [ ] TC-02: <criterion>
## Test Plan
<!-- Derived from type + tags. One row per TC-N. -->
| TC-ID | Test Type | Tool / Approach | Notes |
| ----- | --------- | --------------- | ----- |
| TC-01 | <type> | <tool> | |
| TC-02 | <type> | <tool> | |
## Tasks
- [ ] `.agents/tasks/<ID>.md` — 미생성 (GATE-APPROVAL 통과 후 생성)
## Evidence Log
Section-by-Section Authoring Guide
Frontmatter
type — choose exactly one from the 11-prefix taxonomy:
| Prefix | Nature | SDLC Basis |
|---|
SCREEN | UI / visual output (web, terminal, mobile) | IEEE 830 UI Requirements; ISO/IEC 25010 Usability |
API | HTTP / WebSocket / RPC / MCP interface | IEEE 830 External Interface; REST/RPC contracts |
FLOW | Multi-step user/agent interaction sequence | IEEE 830 Use Case; SDLC User Story |
BEHAVIOR | System-internal execution, state transitions | IEEE 830 Functional Requirements; ISO/IEC 25010 Reliability |
DATA | Schema, type contract, data model | IEEE 830 Data Requirements; ISO/IEC 25010 Data model |
RULE | Business logic, validation, constraints | IEEE 830 Functional Requirements; ISO/IEC 25010 Functional suitability |
AGREEMENT | Cross-system / cross-team boundary contract | SLA; Consumer-Driven Contracts |
INFRA | Build, deploy, CI/CD | IEEE 830 Design Constraints; Deployment Spec |
PERF | Performance contract (latency, throughput, cost) | ISO/IEC 25010 Performance Efficiency |
SECURITY | Auth, threat boundary, data protection | ISO/IEC 25010 Security; OWASP Secure SDLC |
OBSERVABILITY | Logs, metrics, traces, event emission contract | ISO/IEC 25010 Maintainability; SRE 3 Pillars |
tags — YAML array, pick all that apply:
Environment / Platform (determines test tooling):
web · mobile-web · desktop · cli · ios · android
Protocol / Format (determines verification method):
rest · websocket · mcp · json-schema · typescript
NFR cross-cutting (triggers additional test requirements):
i18n · a11y · async · streaming · realtime · auth
Test strategy — derive from the table below and write it in ## Test Plan header or preamble:
| Type | Tags | Derived test strategy |
|---|
| SCREEN | web / desktop | Playwright E2E |
| SCREEN | mobile-web | Playwright E2E (mobile viewport) |
| SCREEN | cli | Process spawn + stdout assertion |
| SCREEN | i18n | Locale rendering test |
| SCREEN | a11y | axe-core accessibility test |
| API | rest | HTTP integration test |
| API | websocket | WebSocket integration test |
| API | mcp | MCP protocol integration test |
| FLOW | web / mobile-web | Playwright E2E scenario |
| FLOW | cli | Process integration test |
| FLOW | agent | Agent simulation E2E |
| BEHAVIOR | async | Async state assertion integration test |
| BEHAVIOR | streaming | Stream output integration test |
| DATA | json-schema | Zod / JSON Schema validation test |
| DATA | typescript | vitest-expect-type / tsd type test |
| RULE | (any) | Unit test |
| AGREEMENT | (any) | Consumer-driven contract test |
| INFRA | ci | CI pipeline smoke test |
| PERF | (any) | Benchmark test (timing assertions) |
| SECURITY | auth | Auth integration + permission boundary test |
| OBSERVABILITY | (any) | Log / event emission assertion test |
Multiple tags → list all derived strategies, one per line.
## Problem
Minimum required content:
- Concrete symptom — what command, code path, or output is wrong
- Reproduction condition — when and where it occurs
Rejected (GATE-WRITE will FAIL): "TBD", vague single sentence, "It doesn't work correctly"
## Prior Art Research
DEFAULT-ON (research.md). Dispatch the prior-art-researcher agent (the research
WORKER) and paste its returned block here; its recommendation feeds Alternatives Considered / Decision.
Minimum required content:
- Comparable commercial products / OSS / AI-agent references, cited from PRODUCT DOCS (docs, API refs, design
docs, release notes, protocol specs) — NOT third-party source code (
research.md).
- The observed common behavior across them + the constraint that applies to Robota.
- ≥1 documentation citation (http link) OR an explicit "no comparable reference found".
Opt out only with an explicit Waived: <reason> line — a waiver you propose (research genuinely
unnecessary) or the user requests.
Rejected (GATE-WRITE + scan-spec-research.mjs will FAIL): missing section, a bare/placeholder section,
or a "TODO" with no citation and no waiver.
## Architecture Review
### Affected Scope
List every package, layer, and file that changes. Format: packages/<name> / <file path>.
### Alternatives Considered
Minimum 2 alternatives. For each: one-line description + Pro + Con.
### Decision
Which alternative was chosen and why. Reference the trade-off.
For a contract-boundary or wide-blast-radius change, the Decision must also record that the chosen
design was validated before approval — reachability by every consumer (incl. dependent/planned),
capability preservation vs. any replaced contract, and an adversarial pass over its failure modes. See
spec-workflow.md "Validated Recommendation Before Approval".
### Architecture Review Checklist
All 4 items must be [x] before GATE-WRITE can pass:
- Normal:
- [x] 영향 패키지/레이어 목록 작성 완료
- Sibling scan N/A:
- [x] Sibling scan 완료 — N/A: not a CLI command family
- Sibling scan done:
- [x] Sibling scan 완료 — agent-cli {chat,print,init} 전부 확인
Never leave [ ]. Unchecked = work not done.
## Fallback & Degradation Declaration
HARNESS-028. Default None. Declare every INTENTIONAL fallback / graceful-degradation / silent
catch → default this change introduces, and justify each — why it is a sanctioned single-path decision,
not a hidden alternative that violates the No Fallback Policy (operational.md).
proposal-reviewer reviews this section at GATE-APPROVAL. The mechanical floor
(scripts/harness/scan-no-fallback.mjs) independently requires each sanctioned code site to carry an
// allow-fallback: <reason> annotation. If the change introduces no fallback, write exactly None — do
not omit the section.
## Completion Criteria
Rules:
- Every item MUST have a
TC-N prefix (TC-01, TC-02, …) — no exceptions.
- Write BEFORE implementation begins.
- Minimum 1 criterion per distinct feature or sub-item.
- Two accepted forms:
- Command form (preferred):
TC-01: <command> → exits <code> / outputs <string>
- Observable behavior form (visual/terminal): exact string, ANSI code, specific observable output
Rejected (GATE-WRITE will FAIL):
- Item without TC-N prefix
- "Works correctly", "No errors", "Feature is implemented"
- "Displays correctly" (too vague)
## Test Plan
Rules:
- One row per TC-N item in
## Completion Criteria.
- Derive Test Type + Tool from the type + tags derivation table.
- If a TC-N cannot be covered by automated test: write the reason in Notes and mark
manual.
Doc / process backlogs (e.g. INFRA skill/rule/docs edits):
- Prefer command-form / CI-smoke rows over
manual. Most doc/process criteria are mechanically
checkable — use an rg pattern (presence/absence of a phrase, anchor, or section) or a
pnpm harness:* smoke (e.g. pnpm harness:scan exit 0) as the Tool/Approach.
- A
manual row is the exception, not the default, even for prose changes.
manual Tool rows REQUIRE a Notes infeasibility justification:
- Any row whose Tool is
manual MUST carry a non-empty Notes entry explaining why automation is
infeasible (e.g. "guidance quality is a human judgement; no command asserts prose correctness").
- A
manual row whose justification is missing — or that a command-form check could have covered —
fails GATE-WRITE.
Rejected (GATE-WRITE will FAIL):
- Missing row for any TC-N
- "TBD" in Test Type or Tool
- No Notes entry when Tool is "manual"
## Tasks
Leave placeholder at draft time. Populated by backlog-gate-guard at GATE-IMPLEMENT.
## Evidence Log
Leave empty at draft time. All entries written by backlog-gate-guard. Never write manually.
What This Skill Does NOT Do
- Run any gate or make PASS/FAIL decisions → that is
backlog-gate-guard
- Update frontmatter status → that is
backlog-pipeline
- Write Evidence Log entries → that is
backlog-gate-guard
- Decide which test type to use beyond the derivation table
