Templates for Work-items of different types

Purpose: Paste-and-fill markdown templates per work-item type — Component, Page, Defect, Integration, Sync, Backend Endpoint, Backend Deletion, QA Acceptance Criteria. Each section has a template you can copy into a new WI plus a short note on what the platform reads.

Reading time: ~10 minutes · Audience: BA / analyst, tech lead · The five composition principles are in Work-Item Description Composition. The per-WI lifecycle is in The Lifecycle of one Work-item.

Below, each WI type gets:

A paste-and-fill template — copy into the WI description field, replace the placeholders, ship.
What the template does — why this shape and what the analyst / developer agent will read from it.
The anti-pattern — the version that produces an abandoned session.

Component (UI)

Template — paste into the WI Description field and replace <…>:

## Component
<Component name — kebab-case, matches the Figma frame name>

## Parent page
<Sibling / parent page WI: WI-NNNN>

## User story
<As a <role>, I see <what> so that <why>. One paragraph max.>

## Display rules
IF <condition> THEN <element / state> with tooltip text - '<literal tooltip>'
IF <condition> THEN <element / state>

## Reuse hint (optional — include when a sibling exists)
Use the approach and patterns of <Sibling component, WI-NNNN>.

## Scope-out
<X is out of scope; what to use instead.>

## Figma
<Specific frame URL — not the whole file.>

## Implementation Hints (optional)
- <Project-specific architectural pin or workaround — see Work-Item Description Composition § Implementation Hints>

What the template does. The user story tells the analyst what the component is for; the display rules block is consumed verbatim by the analyst's work-on-component-logic toolset; the sibling reference (when included) reuses cached agent knowledge from a previous WI; the Figma link tells fetch-figma-data exactly which node to read. The Implementation Hints section captures non-functional / workaround instructions outside the business description.

Anti-pattern: run-on parameter prose with mismatched event counts ("should trigger three events" listing five) — the analyst reads it as narrative and produces narrative-shaped code.

Page (UI)

Template:

## Page
<Page name — kebab-case, matches the Figma frame name>

## User story
<As a <role>, I open <page name> so that <outcome>. One paragraph max.>

## Sibling reference (optional — include when a sibling exists)
Use the approach and patterns of <Sibling page, WI-NNNN>.

## Breadcrumb (optional — include when the path is not obvious from the route)
<Home > Section > Subsection > Page>

## Components on this page
- <Component name 1, WI-NNNN — already shipped>
- <Component name 2, WI-NNNN — already shipped>

## Mock-data shape
<One-line description, e.g. "list of Customer rows with name, status badge, last-payment date">

## Scope-out
API integration is out of scope. Use mocked data. Request params: <list>.
<Authentication / real-time / other> is out of scope.

## Figma
<Specific frame URL.>

## Implementation Hints (optional)
- <Project-specific architectural pin or workaround — see Work-Item Description Composition § Implementation Hints>

What the template does. The page name tells the analyst where the page sits in the app; the components list tells it what placeholders to import (it will not re-onboard components that exist); the mock-data shape tells it what mock service to generate; the scope-out is the single highest-leverage line on the page. The Implementation Hints block carries non-functional rules (architectural placement, env-var externalisation, Storybook linkage). Acceptance criteria are not authored here — /swifter-frontend-analyst:generate-acceptance-criteria derives them from the user story, scope-out, and any conditional logic in the body.

Anti-pattern: "See code for X page" without component list or scope-out — the analyst guesses at three different things simultaneously. Anti-pattern: authoring AC drafts in the WI body — the analyst command overwrites them, so the drafting effort is wasted.

Defect (UI)

Template:

## Observed behaviour
On <page name>, when the user <interaction>, <broken result>.

## Expected behaviour
On <page name>, when the user <interaction>, <correct result>.

## Reproduction
1. <Step 1 — only if multi-step>
2. <Step 2>
3. <Step 3>

## Original WI
<WI-NNNN that produced the broken artefact — required for defects.>

## Figma
<Specific frame URL.>

## Implementation Hints (optional)
- <Project-specific architectural pin or workaround — see Work-Item Description Composition § Implementation Hints>

What the template does. The Observed / Expected pair is the entire description for a single-control visual bug — no reproduction steps needed. Multi-step triggers or backend defects add the Reproduction: section. The Original WI link lets the developer agent diff the spec against the implementation. Defects route through autonomous triage (/swifter-default:start), not through the analyst.

Anti-pattern: routing a defect through the analyst — the analyst writes a spec for a one-line fix, the WI inflates to 2+ sessions for no benefit.

Integration (UI ↔ BE)

Template:

## Integration target
Wire <Page name, WI-NNNN — already shipped on mocks> to <endpoint>.

## Endpoint
<HTTP method> <path>, e.g. GET /api/customers

## Swagger reference
<Link to the Swagger / OpenAPI document or the WI that produced it.>

## Example response
```json
{
  "items": [
    { "id": "c-001", "name": "...", "status": "...", ... }
  ]
}

UI ↔ API mapping

UI element	Endpoint	Field	Transformation
Customer name	GET /api/customers	item.name	—
Status badge	GET /api/customers	item.status	enum → label/colour (see ref data)
Remaining amount	GET /api/customers	computed	item.principal − item.paid
Last payment	GET /api/customers	item.payments[-1].date	ISO → locale short date; null → "never"

Computed-field rules

Remaining: principal − paid (BRD §4.2)
Display "never" when payments array is empty.

Scope-out

Page authoring is out of scope (already shipped). Only wire to the live endpoint.

Implementation Hints (optional)

<Project-specific architectural pin or workaround — see Work-Item Description Composition § Implementation Hints>

**What the template does.** The mapping table is the entire artefact the analyst's updated `functions.yaml` keys off, and the developer agent's `work-on-component-logic` + `generate-page` regeneration produces a mapper / client wiring from. Computed fields and empty / null behaviour must be explicit — what is not in the mapping table, the agent invents. (Swifter has no dedicated `integrate-api` command; the integration is the existing analyst-then-developer arc, re-run against the existing page with the updated function spec — see Journey 3 for the command-by-command walkthrough.)

**Anti-pattern:** *"see Swagger, ask if unclear"* without endpoint path — produces an `Origin → ABANDONED → DONE` cycle. **Anti-pattern:** folding integration into the Page WI — bloats the WI past the canonical arc and destroys the discrete checkpoint where mapping correctness is verified.

## Sync / Maintenance (UI)

**Template:**

```markdown
Synchronize latest changes

What the template does. Title-as-description is the canonical specimen. The sync-component-specs skill reads the source tree, diffs each component against its spec, and updates the specs in place. Hard rule: do not improve these. Adding hints creates extra surface for misinterpretation; in production engagement data, sync items consistently complete in one session on this minimal pattern.

The exception does not generalise. Other one-session arcs — defects, integrations, deletions — still benefit from explicit detail; only the sync skill's surface is small enough that brevity wins.

Backend Endpoint (new endpoint with mocked data)

Template:

## Endpoint
<HTTP method> <path>, e.g. GET /api/customers

## Request
- Path params: <name + type, or "none">
- Query params: <name + type + required/optional>
- Body: <schema or "none" for GET/DELETE>

## Response
- Status 200: <schema> — example below
- Status 4xx: <error schema>

### Example 200 response
```json
{ "items": [ { ... } ] }

Domain model

Entity:
Attributes: <name, status, principal, paid, payments[]>
Source mock file: <src/main/resources/mocks/customers.json>

Enums

Status: one of ACTIVE, OVERDUE, CLOSED
IF Status = OVERDUE THEN colour = red, badge = "Overdue"
IF Status = CLOSED THEN colour = grey, badge = "Closed"
IF Status = ACTIVE THEN colour = green, badge = "Active"

"Always shown" fields

id, name, status, principal — never omit.

Source-file mapping per scenario

IF Status = ACTIVE THEN USE mocks/customers_active.json
IF Status = OVERDUE THEN USE mocks/customers_overdue.json
(others fall back to mocks/customers.json)

Implementation Hints (optional)

<Project-specific architectural pin or workaround — see Work-Item Description Composition § Implementation Hints>

**What the template does.** The Endpoint section tells the backend analyst what scoped specification to produce; the Domain model tells it what entity to wire to a controller; the Enums section drives both the API schema and the FE display rules in subsequent Integration WIs; the source-file mapping wires the controller to mock data without requiring a database.

**Anti-pattern:** re-creating the work item daily with a vague title (*"Reconciliation API attempt 2"*) instead of fixing the description — production engagement data has shown up to 9 attempt-named WIs on one endpoint before the description was fixed.

## Backend Deletion

**Template:**

```markdown
Remove the <endpoint or class> endpoint and related methods and models.

## Callers (do not break)
- <WI-NNNN that calls this endpoint, link>
- <WI-NNNN that calls this endpoint, link>

What the template does. Target + scope of related artefacts is the floor. The callers list lets the developer agent know which other WIs may need to be re-run after the deletion.

QA Acceptance Criteria

Template:

## Page or Component
<Page or component, WI-NNNN — must exist with a spec the QA Tester can read>

## Numbered, testable acceptance criteria
- AC-1: <When the page loads, ... is visible.>
- AC-2: <When the user clicks ..., ... happens.>
- AC-3: <When the response is empty, ... is shown.>
- AC-4: <Edge case ... results in ....>

What the template does. The acceptance criteria become the input to swifter-tester:generate-test-cases and ultimately to Playwright scripts. Numbered, observable, testable — no Figma URL needed, no implementation references.

Choosing a type

Shape of the work	Type to pick
A reusable UI element from a Figma node	Component
A composed screen with state and routing	Page
A single-control visual or behavioural bug	Defect
Wiring a page on mocks to a real endpoint	Integration
Bringing existing code under spec coverage	Sync
A new HTTP endpoint with mocked data	Backend Endpoint
Removing an endpoint and its callers	Backend Deletion
Numbered, testable assertions for a page	QA Acceptance Criteria

If the work doesn't fit any of the above, the breakdown is wrong — return to Scope Preparation and Refinement and split into pieces that do fit.

Component (UI)​

Page (UI)​

Defect (UI)​

Integration (UI ↔ BE)​

UI ↔ API mapping​

Computed-field rules​

Scope-out​

Implementation Hints (optional)​

Backend Endpoint (new endpoint with mocked data)​

Domain model​

Enums​

"Always shown" fields​

Source-file mapping per scenario​

Implementation Hints (optional)​

QA Acceptance Criteria​

Choosing a type​

Component (UI)

Page (UI)

Defect (UI)

Integration (UI ↔ BE)

UI ↔ API mapping

Computed-field rules

Scope-out

Implementation Hints (optional)

Backend Endpoint (new endpoint with mocked data)

Domain model

Enums

"Always shown" fields

Source-file mapping per scenario

Implementation Hints (optional)

QA Acceptance Criteria

Choosing a type