Skip to content

Common: feature with tests

Based on: walkthrough WT-04 · Skills: Requirement, then Implement · Depth: Normal · Status: illustrative, NOT_RUN

Goal

Section titled “Goal”

Add Excel export of filtered orders. Fields and permissions are unresolved at the start.

Concepts demonstrated

Section titled “Concepts demonstrated”
  • Evidence classes: facts versus proposals versus open decisions.
  • Readiness versus task status: a DONE draft with DECISION_REQUIRED readiness.
  • The hand-off: READY_FOR_IMPLEMENTATION does not start implementation.
  • Verification: real check records bound to the final state.

Files involved (synthetic project)

Section titled “Files involved (synthetic project)”
File Role
src/orders/OrderQueryService.ts Existing filtering logic (inspected)
src/invoices/exportCsv.ts Closest existing export pattern (inspected)
src/orders/exportExcel.ts New implementation (written in phase 2)
src/orders/exportExcel.test.ts New tests (written in phase 2)
.kiyo/memory/conventions.md Relevant Memory entry (read, validated)

Phase 1: requirement

Section titled “Phase 1: requirement”

Select Requirement:

Draft requirements for Excel export using repository evidence. Identify unresolved fields and permissions; do not implement.

Expected outcome:

Requirement draft (excerpt, illustrative)
Requirement ID: REQ-EXPORT-01
Objective: Managers can export the currently filtered order list to .xlsx.
Existing facts: Filtering in OrderQueryService (src/orders/OrderQueryService.ts);
  CSV export pattern in src/invoices/exportCsv.ts; no Excel library present.
User requirements: export filtered orders to Excel (request).
AI proposals: reuse the invoice export structure; stream rows for large lists (unapproved).
Unresolved decisions: (1) which roles may export; (2) which columns; (3) row limit.
Acceptance criteria: AC-1 … AC-4 drafted; AC-2/AC-3 depend on decisions (1) and (3).


Implementation readiness: DECISION_REQUIRED — roles and row limit are business decisions.
Task status: DONE (draft delivered). Memory impact: NONE. Files written: none.

You then make the decisions, for example: “Managers and Admins; columns A–F; limit 50,000 rows.” A refreshed draft can reach READY_FOR_IMPLEMENTATION. Requirement still stops there.

Phase 2: implementation

Section titled “Phase 2: implementation”

Select Implement. This is a separate, explicit request:

Implement the approved export requirement within the agreed module; add necessary tests and run authorized local checks after inspecting their effects.

Expected behavior:

  1. Baseline: records the branch and uncommitted changes; runs nothing yet.
  2. Pattern first: mirrors the invoice export structure instead of inventing a new abstraction.
  3. Dependency assessment: an .xlsx library is a new dependency. It is justified and inspected (source, license, scripts). Adding it is not automatically high risk, but under the Stricter approval preset it would need explicit approval.
  4. Tests: adds cases for AC-1 to AC-4, covering the permitted role, the denied role, the row limit, and the empty result.
  5. Verification: inspects the test script, then runs the focused tests and records each check.
Verification excerpt (illustrative)
| Check | Status | Observed result |
| --- | --- | --- |
| CHK-1 unit: exportExcel.test.ts (AC-1..AC-4) | PASS | 4 passed; exit 0 |
| CHK-2 type check (tsc --noEmit) | PASS | exit 0 |
| CHK-3 full suite | FAIL | 1 failure in src/legacy/report.test.ts — baseline (fails on HEAD without this change) |
| CHK-4 e2e export download | NOT_RUN | no browser environment available; still required |


Status: PARTIALLY COMPLETE — CHK-4 is required and not run; the baseline failure remains.
Memory impact: UPDATE_REQUIRED — new export convention; pending authorization to sync.

The report does not say “all tests pass”: the baseline failure is kept and the e2e check is unrun.

Why it is structured this way

Section titled “Why it is structured this way”

Keeping Requirement and Implement separate means business decisions (roles, limits) are made by a human, visibly, before code encodes them. The final status reflects the evidence: a required unrun check prevents DONE, even when the new tests pass.

Section titled “Related”