Decision Log: Multi-PDF Print and Bugs
Purpose
Section titled “Purpose”Tracks scoping and design decisions for the Multi-PDF Print and Bugs project, covering feature organization, persona assignment, field mapping, batch behavior, and API diagnostic parameters.
Decision Table
Section titled “Decision Table”| # | Question | Status | Decision | Round |
|---|---|---|---|---|
| DQ-001 | Feature location and domain code | Decided | SAC::PRINT under features/printing/ | R1 |
| DQ-002 | Print status scope | Decided | Kanban cards only (minimum change) | R1 |
| DQ-003 | Print Diagnostics — same or separate feature doc | Decided | Separate feature doc, same directory | R1 |
| DQ-004 | Notes field mapping for Documint | Decided | Document both fields; correct mapping per type | R1 |
| DQ-005 | KanbanCard.notes editability — scope | Decided | Document intent; frontend UI out of scope | R1 |
| DQ-006 | Printing personas | Decided | All personas listed; design favors Irene | R1 |
| DQ-007 | live-print parameter in feature doc | Decided | Document as diagnostic parameter | R1 |
| DQ-008 | Purchase Order PDF in Printing feature | Decided | Out of scope completely | R1 |
| DQ-009 | Batch size limiting — configurability | Decided | Per-call and per-request; defaults only | R1 |
| DQ-010 | Customer Support persona | Decided | New persona draft required | R1 |
| DQ-011 | Print History API (#792 Option 1) | Deferred | Defer to future project | R1 |
Round 1: Project Scoping
Section titled “Round 1: Project Scoping”DQ-001: Feature Location and Domain Code
Section titled “DQ-001: Feature Location and Domain Code”Context: Printing spans two domains — items (labels/breadcrumbs) and kanban resources (cards). The Documint integration is also used by Purchase Orders. The question is where to locate the feature documentation.
| Option | Description | Trade-offs |
|---|---|---|
| A | Cross-cutting feature under general-behaviors/ (e.g., GEN::PRINT) | Aligns with cross-cutting pattern; but printing has its own domain model (templates, sizes, statuses) unlike generic behaviors |
| B | Split: item printing under REF::ITM, card printing under RES::KAN | Follows entity ownership; but fragments a unified capability across two locations |
| C | New feature area under features/printing/ with SAC::PRINT code | Unified location; printing is a significant Shop Access capability; allows sub-documents for diagnostics |
Recommendation: Option C — Printing is a distinct Shop Access capability with its own domain model.
Decision: Option C. SAC (Shop Access) is the correct domain. Feature docs go in features/printing/.
Applied to:
- Goal § Deliverables and Reviews
DQ-002: Print Status Scope
Section titled “DQ-002: Print Status Scope”Context: Currently only Kanban Cards track print status (NOT_PRINTED/PRINTED with state machine). Ticket #595 asks to “unmark as printed.” The question is whether to extend print status tracking to labels and breadcrumbs.
| Option | Description | Trade-offs |
|---|---|---|
| A | Document print status as kanban-card-only (current state + unmark fix) | Minimum change; aligns with tickets; no new backend work for items |
| B | Extend print status tracking to labels and breadcrumbs | More complete; but significant new work not requested by any ticket |
Recommendation: Option A — Minimum change, aligned with ticket scope.
Decision: Option A. Print status remains kanban-card-only. The unmark capability is documented as a new feature for the existing state machine.
Applied to:
- Feature document § Print Status Lifecycle
DQ-003: Print Diagnostics — Same or Separate Feature Document
Section titled “DQ-003: Print Diagnostics — Same or Separate Feature Document”Context: Tickets #762 and #792 request debug/history capabilities for support teams. This serves a different persona (Customer Support) than the main printing features (Irene/operators).
| Option | Description | Trade-offs |
|---|---|---|
| A | Single feature doc with persona-scoped sections | Simpler structure; but mixes end-user and support concerns |
| B | Separate feature doc in the same printing/ directory | Clean separation of concerns; each doc targets its persona; allows independent lifecycle |
Recommendation: Option B — Clean persona separation.
Decision: Option B. Separate diagnostics.md in the same features/printing/ directory. A new Customer Support persona is required.
Applied to:
- Feature document structure
- DQ-010
DQ-004: Notes Field Mapping for Documint
Section titled “DQ-004: Notes Field Mapping for Documint”Context: Bug #815 reports that the Documint payload sends item.notes (order history) instead of item.cardNotesDefault in the notes field. Bug #816 says cards should not show notes when card_notes is empty. The question is how to document the correct mapping.
| Option | Description | Trade-offs |
|---|---|---|
| A | Define the correct field mapping as a simple requirement | Quick; but doesn’t document the intent behind the two fields |
| B | Document both fields and their intended purposes; correct mapping flows from the specification | More complete; provides context for future changes |
Recommendation: Option B — The distinction between notes and cardNotesDefault is non-obvious without documentation.
Decision: Option B with a caveat: The original intent is that KanbanCard.notes is editable per card. It gets its initial value from Item.cardNotesDefault ?: Item.notes but then evolves independently. When printing:
- Cards: The field to print is
KanbanCard.notes - Labels and Breadcrumbs: The field to print is
Item.notes
Applied to:
- Feature document § Payload Mapping
- Bug fix implementation for #815 and #816
DQ-005: KanbanCard.notes Editability — Scope
Section titled “DQ-005: KanbanCard.notes Editability — Scope”Context: The backend has a PUT /v1/kanban/kanban-card/{eId}/notes endpoint and intelligent sync logic. The frontend API route exists but no UI component calls it. The KanbanCard TypeScript type doesn’t even include a notes field.
| Option | Description | Trade-offs |
|---|---|---|
| A | Document the intended behavior; frontend UI for card notes editing out of scope | Documents the full vision without requiring new UI work in this project |
| B | Include frontend card notes editing UI in project scope | Significant new work; not requested by any ticket |
Recommendation: Option A — Correct scoping: document intent, defer UI.
Decision: Option A. The feature description documents the intended behavior (card notes are independently editable per card). The requirements note that frontend UI for card notes editing is out of scope for this project. The bug fix (#815/#816) focuses on ensuring the correct field is sent to Documint.
Applied to:
- Feature document § Payload Mapping (notes field intent)
- Out-of-scope section
DQ-006: Printing Personas
Section titled “DQ-006: Printing Personas”Context: Printing is primarily Irene’s responsibility (setup, printing, floor walks), but David (reprint after ordering) and Keisha (reprint after receiving) also print.
| Option | Description | Trade-offs |
|---|---|---|
| A | Focus on Irene only | Simpler; but misses secondary use |
| B | List all personas; design favors Irene | Complete picture; design trade-offs resolve in Irene’s favor when personas conflict |
Recommendation: Option B.
Decision: Option B. All personas who print are listed. Design trade-offs favor Irene as the primary printing persona.
Applied to:
- Feature document § Summary (personas list)
DQ-007: live-print Parameter in Feature Doc
Section titled “DQ-007: live-print Parameter in Feature Doc”Context: The backend has a live-print query parameter controlling Documint preview vs. live rendering. The intent is to distinguish “production” requests (counting against Documint quota) from “test” requests (watermarked output, no quota impact).
| Option | Description | Trade-offs |
|---|---|---|
| A | Omit — implementation detail | Simpler doc; but loses important operational context |
| B | Document as a diagnostic parameter alongside other API diagnostic capabilities | Groups all diagnostic parameters; provides operational context for support teams |
Recommendation: Option B — Groups naturally with the diagnostic features.
Decision: Option B. Document live-print together with other diagnostic parameters (debug flag, dry-run) in the Print Diagnostics feature document.
Applied to:
- Print Diagnostics feature document
DQ-008: Purchase Order PDF in Printing Feature
Section titled “DQ-008: Purchase Order PDF in Printing Feature”Context: The Purchase Order module also uses Documint for PDF generation (PRO::PO::0006::0002.FS). The question is whether to reference this shared pattern.
| Option | Description | Trade-offs |
|---|---|---|
| A | Reference PO PDF as a shared Documint pattern | Shows the full picture; but may confuse scope |
| B | Treat PO printing as completely separate | Clean scope; PO has its own feature lifecycle |
Recommendation: Option B — Keep scope clean.
Decision: Option B. Purchase Order PDF generation is completely out of scope for this feature description.
Applied to:
- Feature document scope boundary
DQ-009: Batch Size Limiting — Configurability
Section titled “DQ-009: Batch Size Limiting — Configurability”Context: Currently there is no batch size limiting. Ticket #519 reports that >40 items causes Documint failures. The question is where limits apply and how they’re configured.
| Option | Description | Trade-offs |
|---|---|---|
| A | Per Documint call only | Simple; but doesn’t protect against excessive total items |
| B | Per user request only | Limits total load; but a single large template group still overloads Documint |
| C | Both, with separate config values | Complete protection; two knobs to configure |
Recommendation: Option C — Both limits serve different purposes.
Decision: Option C. Both per-call and per-request limits. However, these are not user-configurable — they are system design/configuration values determined at build and deploy time. The feature documents the defaults and notes them as system configuration. Future user-configurable limits via the OAM console are out of scope.
Applied to:
- Feature document § Batch Size Limiting
DQ-010: Customer Support Persona
Section titled “DQ-010: Customer Support Persona”Context: Print Diagnostics features (#762, #792) serve Arda’s internal support and customer success teams. No existing persona matches this role.
| Option | Description | Trade-offs |
|---|---|---|
| A | Create a new Customer Support persona | Proper persona-driven design; reusable for future support features |
| B | Document diagnostics without a persona | Faster; but loses the user context that drives design trade-offs |
Recommendation: Option A.
Decision: Option A. Create a draft persona: “An Arda employee who provides product and technical support to customers and develops specialized applications using Arda’s API for custom purposes.”
Applied to:
product/personas/charlie-customer-support.md(new)- Print Diagnostics feature document (persona reference)
DQ-011: Print History API (Ticket #792 Option 1) — Deferred
Section titled “DQ-011: Print History API (Ticket #792 Option 1) — Deferred”Context: GitHub ticket #792 proposes two options: (1) a Print History API for querying past print jobs, and (2) a dry-run/debug flag approach. The project implements Option 2 only.
| Option | Description | Trade-offs |
|---|---|---|
| A | Defer Option 1 to a future project | Covers the primary troubleshooting use case via debug/dry-run; historical query and proactive monitoring (#792 workflow #3) are not addressed |
| B | Include Option 1 in this project | Significant additional scope: new persistence layer for print events, new query endpoint, new API types |
Recommendation: Option A — The debug/dry-run approach covers the immediate troubleshooting need. Print history requires architectural work (event persistence, query API) that is out of proportion for this project.
Decision: Option A. The Print History API (#792 Option 1) is deferred. The proactive monitoring use case (Coda dashboard flagging print failures across tenants) is not covered by this project and should be tracked as a separate future initiative.
Applied to:
- Analysis § Finding 10
Copyright: (c) Arda Systems 2025-2026, All rights reserved
Copyright: © Arda Systems 2025-2026, All rights reserved