Task writing standard

A shared standard for creating tasks that a person or agent can execute without guessing. Choose one task type, complete every applicable field, and name the role responsible for each input.

4
Task types
8
Named roles
27
Fields in the full reference
1 type
Per task—split mixed work
The readiness rule

A task is ready when every applicable field has clear content and a named owner. Do not assign it to an agent before that condition is met.

On this page

  1. Readiness rule
  2. Task types
  3. Roles
  4. Field reference
  5. Full sample: story
  6. Full sample: bug
  7. Full sample: tech
  8. Full sample: ops

1. Readiness rule

2. Task types

USER-VISIBLE
story
New or changed user-visible behavior. The PO is the primary author.
DEFECT
bug
Observed behavior that differs from expected behavior. The reporter is the primary author.
INTERNAL
tech
Refactoring, tooling, types, tests, or other internal improvements. The lead is the primary author.
PRIVILEGED
ops
Infrastructure, releases, secrets, settings, or third-party consoles. DevOps is the primary author.
Type Use it for Primary author Agent ownership
story New or changed user-visible behavior PO Full after product, design, and verification inputs are complete
bug Observed behavior that differs from expected behavior Reporter Full after the defect is reproducible or scoped as an investigation
tech Refactoring, tooling, types, tests, or other internal improvements Lead Full after the work has a safe slice and a behavior budget
ops Infrastructure, releases, secrets, settings, or third-party consoles DevOps Partial when a step needs privileged access
Naming rule

Keep ops as the task type. Use DevOps as the role name.

3. Roles

These names describe responsibilities. One person can perform several roles.

PO
Owns the outcome, business rules, priority, and product-supplied data.
Design
Owns the design source and all required interface states.
Lead
Owns scope, size, slice boundaries, sequencing, and debt metrics.
Dev
Owns technical context, verification, known traps, and root-cause analysis.
Grooming
Owns the task type, acceptance-criteria wording, size, and readiness decision.
DevOps
Owns privileged systems, access, runbooks, rollback, and operational evidence.
Reporter
Owns reproduction steps and the observed-versus-expected behavior.
Agent
Owns no task field. The agent uses complete fields and reports unresolved gaps.

4. Field reference

All means every task type. Include each applicable field once.

Field Task type Owner Description Sample
Type All Grooming Select one type before writing other fields. Split work when more than one type applies. story
Outcome All story, bug: PO;
tech: Lead;
ops: DevOps		 State the result in one sentence. Avoid implementation details unless the result is technical. Users can download an invoice as a PDF.
Acceptance criteria All Grooming + outcome owner List 3–7 results that a test or direct observation can prove. A paid invoice downloads as a readable PDF.
Scope All Lead State what is in scope and out of scope. Name file globs, systems, merge hotspots, and required sequencing. In: src/invoices/**. Out: payment logic and email delivery.
Verification All Dev Give exact commands and observations. For ops, require proof outside the repository. Run npm test -- invoices, then download one invoice from the preview.
Context anchors story bug tech Dev Give 3–8 useful paths, symbols, links, operations, or examples to imitate. src/invoices/InvoicePage.tsx; InvoiceQuery; existing receipt download.
Preconditions story bug PO + Dev Name required accounts, permissions, data, environments, feature flags, and entry points. Use the staging billing account with one paid invoice.
Definition of done All Lead State the delivery gates and required evidence. Open a linked PR, pass all gates, verify the preview, and attach evidence.
Size fence All Lead State when the implementer must stop and split or ask for a decision. Stop if the change exceeds five files or needs a schema change.
Known traps story bug tech Dev List relevant repository rules, generated files, sensitive data, and unsafe shortcuts. Run code generation after GraphQL changes. Do not edit generated files.
Design and states story Design Link the source design. List empty, loading, error, success, and narrow-screen states when relevant. Figma node: <url>. Cover loading, empty, error, and 375 px widths.
i18n scope story Dev + PO Name the translation scope, required languages, and approved copy source. Add invoice.download in Thai and English. PO supplies final copy.
Data shape story Dev Name the API operation or model change. State whether generated output should change. Extend InvoiceQuery with pdfUrl; GraphQL code generation will change.
Reproduction bug Reporter Give the environment, route, account, data state, and numbered steps. On staging, open /invoices/42 and select Download twice.
Observed and expected bug Reporter + PO State the current result and the required result as separate facts. Observed: two files download. Expected: one file downloads.
Regression test bug Dev Name the lowest-level test that fails before the fix and passes after it. Add a component test that detects two download requests.
Blast radius bug Dev List affected callers, users, data, and adjacent behavior. The shared download hook is used by invoices and receipts.
Root cause bug Dev Give a code anchor when known. Otherwise require investigation before editing. useDownload.ts:48 registers the click handler twice.
Behavior-change budget tech Lead State every allowed behavior change. Use none when output must stay identical. None. Rendered output and API payloads must remain identical.
Safety net tech Dev Name existing tests or the characterization tests required before editing. Add formatter characterization tests before moving the logic.
Slice boundary tech Lead State the current slice and list later slices that are excluded. Slice 1 of 3. Do not change form validation or API mapping.
Debt metric tech Lead Name a measurable value that must improve. Reduce duplicate formatter implementations from four to one.
Runbook ops DevOps Give ordered, repeatable steps with exact commands or console paths. Add the new token, deploy staging, revoke the old token, then verify.
Split of duties ops DevOps + Lead Separate agent-safe steps from credentialed or production-only steps. The agent updates configuration. DevOps rotates the production token.
Access ops DevOps Name the service, organization, environment, and credential holder. Never include the credential. GitHub organization acme; production access holder: platform lead.
Blast radius and rollback ops DevOps State failure effects, rollback steps, rollback owner, and expected duration. A failed rotation blocks deploys. Restore the old token within five minutes.
Evidence and secret handling ops DevOps Name the required evidence. State how secrets and sensitive values must be handled. Attach the successful run URL. Do not paste token values into the task or PR.
story

5. Full sample: เพิ่มปุ่ม Download PDF ในหน้า Invoice

FieldOwnerSample
TypeGroomingstory
OutcomePOBilling user ดาวน์โหลด paid invoice เป็น PDF ได้
Acceptance criteriaGrooming + PO1. Paid invoice แสดงปุ่ม Download PDF
2. ปุ่มดาวน์โหลด PDF ที่เปิดอ่านได้และมี invoice number ถูกต้อง
3. Unpaid invoice ไม่แสดงปุ่ม
4. Loading และ download error แสดง approved message
5. Integration test ครอบคลุม paid และ unpaid invoice
ScopeLeadแก้ src/invoices/** และ invoice tests
ไม่รวม payment, email และ receipt behavior
VerificationDevรัน npm test -- invoices
เปิด paid invoice บน preview แล้วดาวน์โหลด PDF
Context anchorsDevดู InvoicePage.tsx, InvoiceQuery และ receipt download action ที่มีอยู่
PreconditionsPO + Devใช้ staging billing account ที่มี paid invoice และ unpaid invoice อย่างละหนึ่งรายการ
Definition of doneLeadเปิด linked PR และผ่านทุก gate
ตรวจ preview และแนบ screenshot ของ PDF
Size fenceLeadหยุดและขอ split ถ้าต้องเพิ่ม service หรือแก้มากกว่าหนึ่ง GraphQL operation
Known trapsDevรัน GraphQL code generation หลังแก้ query
ห้ามแก้ generated files หรือ log invoice data
Design and statesDesignใช้ Figma node <url>
ครอบคลุม loading, error, paid, unpaid และ 375 px states
i18n scopeDev + POเพิ่ม approved copy ใต้ invoice.download ทั้ง Thai และ English
Data shapeDevเพิ่ม pdfUrl ใน InvoiceQuery
GraphQL generated output ต้องเปลี่ยนตาม schema
bug

6. Full sample: ป้องกัน Invoice ดาวน์โหลดซ้ำ

FieldOwnerSample
TypeGroomingbug
OutcomePOเมื่อ user กด Download PDF หนึ่งครั้ง ระบบต้องเริ่มหนึ่ง download เท่านั้น
Acceptance criteriaGrooming + PO1. หนึ่ง click ส่งหนึ่ง download request
2. Click ซ้ำระหว่าง request ไม่สร้าง request ใหม่
3. ปุ่มกลับมาใช้งานได้หลัง request fail
4. Regression test fail ก่อนแก้และ pass หลังแก้
ScopeLeadแก้ shared download hook และ test เท่านั้น
ไม่รวม PDF generation และ receipt download
VerificationDevรัน npm test -- useDownload
ตรวจ preview network panel ว่ามีหนึ่ง request
Context anchorsDevตรวจ useDownload.ts, InvoicePage.tsx และ invoice download API client
PreconditionsPO + Devใช้ staging billing user ที่มี paid invoice และเปิด browser download ไว้
Definition of doneLeadเปิด linked PR และผ่านทุก gate
แนบ test output ทั้ง fail และ pass
Size fenceLeadหยุดถ้าต้องเปลี่ยน public hook API หรือกระทบ receipt behavior
Known trapsDevห้ามแก้ด้วย fixed delay
Keyboard activation ต้องทำงานเหมือนเดิม
ReproductionReporter1. เปิด paid invoice บน staging
2. กด Download PDF หนึ่งครั้ง
3. พบสองไฟล์ใน browser download list
Observed and expectedReporter + POObserved: Browser ดาวน์โหลดสองไฟล์
Expected: Browser ดาวน์โหลดหนึ่งไฟล์
Regression testDevเพิ่ม hook test ที่ expect หนึ่ง request หลังหนึ่ง click
Blast radiusDevHook นี้ใช้กับ invoice และ receipt download
Receipt behavior ต้องไม่เปลี่ยน
Root causeDevuseDownload.ts:48 register handler ซ้ำหลัง state refresh
tech

7. Full sample: รวม Currency Formatter ให้เหลือจุดเดียว

FieldOwnerSample
TypeGroomingtech
OutcomeLeadInvoice screens ใช้ currency formatter ที่มี test ร่วมกันหนึ่งตัว
Acceptance criteriaGrooming + Lead1. Invoice screens ทุกหน้ import shared formatter
2. Characterization tests pass ก่อนและหลังแก้
3. Rendered currency text ต้องเหมือนเดิม
4. Formatter ไม่มี any type
ScopeLeadแก้ invoice formatters และ tests
ไม่รวม checkout, locale selection และ API payloads
VerificationDevรัน npm test -- currency invoices และ npm run typecheck
เทียบ seeded invoice values บน preview
Context anchorsDevตรวจ invoiceCurrency.ts, InvoiceTotal.tsx, InvoiceRow.tsx และ shared/formatCurrency.ts
Definition of doneLeadเปิด linked PR และผ่านทุก gate
แนบ test output และ preview comparison
Size fenceLeadหยุดถ้าแก้เกินห้าไฟล์หรือ rendered text เปลี่ยน
Known trapsDevรักษา locale rounding เดิม
ห้ามรวม date formatting ใน task นี้
Behavior-change budgetLeadไม่มี
Rendered text และ API payloads ต้องเหมือนเดิม
Safety netDevเพิ่ม characterization tests ให้ formatter เดิมทุกตัวก่อนย้าย logic
Slice boundaryLeadTask นี้คือ slice 1 จาก 2
Slice 2 สำหรับ checkout ไม่อยู่ใน scope
Debt metricLeadลด currency formatter สำหรับ invoice จากสาม implementation เหลือหนึ่ง
ops

8. Full sample: Rotate Deployment Token

FieldOwnerSample
TypeGroomingops
OutcomeDevOpsProduction deploy ใช้ token ใหม่ และ token เก่าใช้งานไม่ได้
Acceptance criteriaGrooming + DevOps1. Staging และ production deploy สำเร็จด้วย token ใหม่
2. Revoke token เก่าหลัง staging check ผ่าน
3. Deploy ด้วย token เก่าต้อง fail
4. Token value ต้องไม่อยู่ใน repository หรือ task
ScopeLeadRotate deployment token หนึ่งตัวใน GitHub และ hosting console
ไม่แก้ build configuration
VerificationDevตรวจ staging และ production run URLs
ยืนยันใน provider console ว่า token เก่าใช้งานไม่ได้
Definition of doneLeadแนบ run URLs และ audit-log screenshots
บันทึก rotation date แล้วปิด task
Size fenceLeadหยุดถ้าต้องเปลี่ยน credential หรือ service อื่น
RunbookDevOps1. ยืนยันว่าอยู่นอก release window
2. สร้าง token ใหม่ด้วย minimum permissions เดิม
3. อัปเดต staging secret โดยยังไม่ revoke token เก่า
4. Deploy และ verify staging
5. อัปเดต production secret
6. Deploy และ verify production
7. Revoke token เก่าและยืนยันว่าใช้งานไม่ได้
Split of dutiesDevOps + LeadAgent ตรวจ configuration และ public runs ได้
DevOps ทำทุกขั้นตอนที่ใช้ token
AccessDevOpsใช้ GitHub organization acme และ production hosting project
Platform lead เป็น access holder
Blast radius and rollbackDevOpsToken ที่ผิดทำให้ deploy ไม่ได้
Restore token เก่าภายในห้านาทีก่อน revoke
Evidence and secret handlingDevOpsแนบ run URLs และ redacted audit screenshots
ห้ามใส่ token value ใน task หรือ PR