Work-Item Description Composition

Purpose: Apply the five universal principles so every work item is one Swifter can execute on first read.

Reading time: ~6 minutes · Audience: BA / analyst, tech lead · The composition discipline is six principles — that's this page. The per-type templates are in Templates for Work-items of different types; the per-WI lifecycle from author to close is in The Lifecycle of one Work-item.

A seventh, optional section — Implementation Hints — sits below the body for non-functional / workaround / architectural-pin instructions; see the dedicated section near the end of this page.

Principle 1 — Agents Read Literally

Quote any text that must appear verbatim, spell out enum values, and never write "as per design" — agents read literally. The failure modes the literal-reading principle prevents:

• "As per design" — the agent does not have an interpreter that resolves vague phrases against the Figma. It will either ignore the phrase and ship the wrong text, or paraphrase the Figma into prose that diverges.
• Unquoted button labels — write Button label: "Process Amortization", not the Process Amortization button. The quote tells the agent the label is a literal string.
• Enum values as "various types" — write Type — one of: A, B, C, D, E, not the various transaction types. The agent's generated code will use the literal list and the display rules will type-check.
• Tooltip text as paraphrase — write Tooltip: "Cannot process while a draft is open", not show a tooltip explaining why the button is disabled.
• Field names — quote field names that come from the API or the data model when they appear in the WI description; the agent will use the quoted string verbatim.

If a piece of text will appear in the UI, in the spec, or in the code, quote it. The agent will copy quotes faithfully and paraphrase prose unpredictably.

Principle 2 — State Scope OUT Explicitly

The single highest-leverage line in a work item is "X is out of scope; use mocked data" — without it, Swifter helpfully builds adjacent functionality. The canonical scope-out phrasings:

• <X> is out of scope; use mocked data.
• <X> is out of scope; will be in WI-YYYY.
• <X> is out of scope; placeholder for now.
• API integration is out of scope. Use mocked data. Request params - <list>.
• Authentication is out of scope; assume the user is logged in.
• Real-time updates are out of scope; static load only.

The phrasing matters because the agent reads the description as a brief, not as a story. Without an explicit out-of-scope line, the agent treats every adjacent capability mentioned anywhere in the Figma or the BRD as a candidate for implementation. The scope-out line is the single cheapest defence against that drift.

Principle 3 — Name a Sibling When One Exists

The sibling reference is optional but highly recommended when an appropriate sibling exists. "Use the approach and patterns of <Sibling Page / Component>" reuses cached agent knowledge from previous work items — the agent already has the sibling's spec, code, and Storybook entry in working memory, so pointing at it lets it inherit shape decisions for free. The breadcrumb on a page WI is similarly optional; include it only if it conveys real navigation context.

When a useful sibling exists, the right ones to name are:

• For a new page — a sibling page in the same feature area, ideally with similar widgets.
• For a new component — a sibling component in the same library family, ideally using the same library wrapper.
• For a new endpoint — a sibling endpoint on the same service, ideally with the same response envelope.
• For a defect — the original WI that produced the broken artefact, named explicitly (this one is effectively required — defects without their origin WI take much longer).

When no suitable sibling exists, omit the line entirely — the agent will not invent one, and including a "no sibling exists" placeholder adds noise without adding signal. The same applies to breadcrumb: skip it when the page is top-level or when the path is obvious from the route.

Principle 4 — Conditional Logic as IF/THEN, Never as Prose

Display rules and business rules go as IF <condition> THEN <element / state>, never as run-on prose; literal tooltip text in quotes. The pattern, lifted from the highest-scored component work items on the pilot:

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

Why it works: each rule is independently parseable, the condition and the consequence are unambiguous, the tooltip text is a literal string the agent will copy verbatim, and the rules can be enumerated and checked against acceptance criteria. The wrong shape is a run-on paragraph that mixes the rule, the rationale, and an example — the agent reads it as a narrative and produces narrative-shaped code.

A component WI with three IF/THEN lines and a quoted tooltip is the canonical 9/9 specimen. A component WI with one paragraph that says "should trigger three events" but lists five is the canonical anti-pattern.

Principle 5 — One Scope per WI

If the description says "and also," split the work item; one work item equals one logically complete unit — one component, one page, one integration. The "one scope" rule generalises the breakdown rules into a description-level test: read the description, look for conjunctions that introduce a second subject, and split if you find one. A work item that says "build the page and also wire up the API" is two work items; a work item that says "build the page" with API integration is out of scope is one.

The cost of violating the rule shows up as Origin → ABANDONED cycles. The agent reads the bundled description, produces a spec that addresses the first half and skips the second, the reviewer marks the session abandoned, and the cycle repeats. Splitting before the first session opens is always cheaper than splitting after the third session abandons.

Principle 6 — Keep Example Data Consistent Across Sources

When a work item carries more than one example of the same thing — a Figma screen and a source JSON, a sample API response and the mockup it feeds — the data must match across all of them. The Figma screen that displays an insurance policy must show the same policy number, holder name, coverage amounts, and dates that appear in the source JSON example. Same data in both, field for field.

The failure mode without it: the agent binds the wrong field, invents a formatting rule that happens to fit the mismatched sample, or hardcodes a value it should have computed — and the defect only surfaces when real data flows through.

How to apply:

• Use one coherent dataset for the whole WI. Pick (or generate) a single realistic example record and use it in every artefact — Figma, JSON, sample responses, acceptance-criteria examples.

Implementation Hints (optional section)

Implementation Hints are a separate, optional section of the WI body that carries non-functional / workaround / architectural-pin instructions — kept apart from the business description so the WI's primary content stays focused on what the user sees, while the technical "how to land cleanly" stays accessible to the agent. Treat them as a temporary measure: as the Swifter platform absorbs each recurring hint into its defaults, the hint can drop out of new WIs.

When to add Implementation Hints

• A previous WI of the same type abandoned a session on the same recurring issue (e.g. the agent hardcoded a URL instead of reading from env vars).
• A project-specific architectural rule does not yet appear in the module's guidelines (e.g. "API service wrappers are shared across multiple pages; locate them separately from page components").
• A platform behaviour that's a known stumbling block needs an explicit nudge (e.g. delegation prompts to subagents).
• The agent has produced wrong artefacts on this kind of work before and the team has a one-line correction.

Do not put functional requirements here — business rules and acceptance behaviours belong in the body of the WI. Implementation Hints are workarounds and conventions, not requirements.

Format

A short bulleted list of one-line technical rules. Drawn from real engagements, the recurring hint families are:

• Component reuse — "Use existing components: Titles, ListItem, AttemptHistory." Naming onboarded components stops the agent from re-creating them.
• API integration target — "Integrate with getTaskDetailScreen (GET /screens/taskDetails/{taskId}) to populate customer context, attempt history, task metadata, and process steps." Endpoint, operationId, and which UI elements it feeds.
• Architectural placement — "API service wrappers are shared across multiple pages; locate them separately from page components."
• Configuration externalisation — "API integration: source the backend base URL from the consumed API library configuration and externalise it through the environment config. All API calls must reference the environment variable — no relative paths, hardcoded URLs, localhost placeholders, or mock fallbacks when a consumed API is defined."
• Storybook linkage — "Stories must import and render the real page component, providing mock API responses via HTTP interceptors at the application config level. Do not create inline wrapper components that duplicate the page's logic."
• Subagent delegation — "When delegating /define-component-spec to a subagent via Task/Agent tool, the prompt MUST instruct the subagent to use the Skill tool. Do NOT use vague prompts like 'invoke the command' — subagents may improvise and create files manually instead of running the full pipeline."

Group the hints into a single ## Implementation Hints block at the end of the WI body; the agent reads the section as a whole and applies the rules across every artefact it produces. After the session, ask the analyst (or developer) to explicitly confirm each hint was honoured — this is the simplest way to catch the agent silently skipping one.

Lifecycle

Hints accumulate bottom-up from observation: when an agent stumbles on something, the fix becomes a hint in the next WI of the same type. As patterns stabilise, hints either (a) graduate into project guidelines (overview/CODING_GUIDELINES.md, the per-module conventions), or (b) get absorbed into Swifter platform defaults and stop appearing in WIs altogether. A growing Implementation Hints section across many WIs is a signal that the guidelines or the platform need an update; a shrinking one is a signal that the platform is improving.

Quality rubric

Work items score on Specificity, Completeness, and Clarity (1–3 each); 7–9 Excellent · 5–6 Good · 3–4 Poor. Poor is acceptable only for sync items.

Dimension	1 — Poor	2 — Adequate	3 — Good
Specificity	Title repeated; "as per design"; *No description.*	General goal + Figma URL or path	User story + scope boundary + sibling reference (if applicable)
Completeness	Missing type / context / scope-out entirely	Some hints, business rules vague	Conditional logic stated, scope-out called out, implementation hints where the agent has stumbled before
Clarity	Run-on prose; "should trigger 3 events" listing 5; mixed normative / example content	Clear intent, some ambiguity	One interpretation only; IF/THEN where rules exist; quoted literals

A score of 3–4 is acceptable only for sync / maintenance work items, where the floor pattern is the right pattern. Any other type that lands at 3–4 should not be assigned to an agent; the description needs work.

Authoring anti-patterns

The most common authoring mistakes observed across engagements. Each row gives the wrong shape, a concrete example, and the fix.

#	Anti-pattern	Example	Fix
1	Over-specifying implementation	"Create a React component, use useState for the form, call axios.post, handle errors in try-catch…"	"Form from Figma (link), on submit POST /api/loans per the mapping table below. Errors: snackbar at the bottom." — name sources of truth, not steps.
2	Incomplete contract	"Endpoint returns a list of loans"	Attach the Swagger JSON or paste an example response with field types.
3	Vibe-coding outside the WI	Manual code edits bypassing Swifter	Any edit → a new WI, even a small one. The discipline only holds when it is total.
4	Vague scope	"Finish the loans page"	One WI = one logically complete unit (one component, one page, or one integration). Split if necessary; state the out-of-scope.
5	Authoring acceptance criteria in the WI body	A ## Acceptance criteria (draft) block in the description	Don't pre-author AC drafts in the WI body — they are generated by /swifter-frontend-analyst:generate-acceptance-criteria (or the backend / tester equivalent) from the user story, scope-out, and rules already in the body. Polishing them upstream is duplicate work the agent overwrites.
6	WI without dependencies stated	"Page depends on a not-yet-built component" but no link	Use linked WI or blocked by explicitly so Swifter sequences correctly.

What comes next

• Work-Item Type Templates — best-practice exemplars and floor patterns for Component / Page / Defect / Integration / Sync / Backend Endpoint / Backend Deletion / QA Acceptance Criteria, plus the "sync WI" exception.
• Work-Item Lifecycle — the 7-step lifecycle every WI follows from author to close.