--- feature_id: FTR-36 title: Excel Tracker (Base Capability) category: Trackers optional: true depends_on: none source: Not from Project_Kickoff_Seed_Prompt_v2.3.md — supplied directly by the user, drafted from real production testing in the Chambers v Chambers project (7 mechanical tests, all passed, against a real 197-row dataset). No corresponding item in Bootstrap_Function_Registry.md. See coverage_report.md Section 10. registry_refs: [] --- # Excel Tracker (Base Capability) Depends on: none ## What this is Defines how the agent creates, reads, edits, and safeguards an Excel (.xlsx) file used as a structured, row-per-item tracker — as opposed to tracking the same information in a markdown table. This is a base capability: it says nothing about what the tracker is for. Domain-specific features (e.g., legal discovery tracking) depend on this spec for their mechanics and add their own schema on top. Use an Excel tracker instead of a markdown table when the data is naturally row-per-item, needs to be filtered/sorted/checked off interactively by the user, and benefits from dropdowns, formulas, or a status field that gets updated repeatedly over the tracker's life. Markdown stays the right choice for prose, reasoning, and strategy content that doesn't decompose into atomic rows. ## Assess first - Confirm whether the data genuinely fits a row-per-item model (see above) before defaulting to Excel just because the source data happens to include a table. - If installing this alongside a domain-dependent feature (e.g., legal discovery tracking) in the same session, install this feature's section first — the domain feature nests under it, not beside it (see Write below). ## Ask, only if needed Nothing to ask before installing this base capability itself — it has no user-facing configuration of its own. A dependent domain feature may have its own Ask step. ## Write ### Access method — PowerShell + Excel COM automation **This is the only tested and approved method for creating or editing an Excel tracker in this environment.** - The agent uses `windows-mcp-*:PowerShell` to drive Excel via COM automation (`New-Object -ComObject Excel.Application`), not `openpyxl`/Python, and not the generic `windows-mcp-*:FileSystem` copy/write modes for the file's binary content. - Excel COM automation is confirmed available in this environment. It produces a genuine, fully-featured .xlsx — real formulas (not hardcoded values), data-validation dropdowns, multiple sheets, cross-sheet references — authored natively on the user's machine, with no file-transfer step. In practice, this combination (PowerShell driving Excel via COM, in-session, on the same machine) is genuinely fast for both the edit itself and the pre-edit backup — this is the actual reason — not just convention — that COM-native is the default and sandbox-then- transfer is rejected below: transferring a file (or splitting one across base64-encoded chunks) gives up real, observed speed for no benefit. - **Do not** build the .xlsx in a separate sandbox/container environment and transfer the finished binary onto the user's filesystem — this was tried and rejected; base64-encoding a binary across that boundary is slow and produces enormous, unreadable tool-call payloads for no benefit over building the file natively where it will live. **Mandatory cleanup:** every script that opens Excel via COM must close the workbook and quit the Excel application object, including on error paths (wrap in try/finally for anything complex enough to risk a mid-script failure). An unclosed COM reference leaves an invisible EXCEL.EXE process running on the user's machine. **When a direct single-pass COM write genuinely can't produce the needed structure** (data needs real assembly or transformation before it maps cleanly into cells/sheets/formulas): this is still not a reason to fall back to the sandbox-then-transfer pattern rejected above. Assemble or compute the data first (still natively, still on the user's machine, same session), then write it down via COM as a distinct second step, once the structure is actually ready. Two native steps — prepare, then write — is fine; a transferred binary is not, regardless of how the data got assembled. Base64-encoding a file across any tool or environment boundary remains rejected outright, for transfer or for splitting a large file into parts alike — if a write genuinely needs priming, prime it locally, then write it locally; never encode-and-move as a substitute for either step. **Known behavior to account for:** Excel auto-reformats values written as date-like strings (e.g., a cell written as `2026-08-09` reads back as `8/9/2026`). If a tracker schema includes a date field, decide explicitly whether it should be a true Excel date value (sortable, formula-compatible) or a fixed text string, and format/write accordingly. ### Backup convention — pre-edit copy, not a periodic archive **Every edit to a tracked Excel file is preceded by a timestamped backup copy.** This is distinct from and in addition to any repository-level backup the user runs separately — a once-daily backup does not protect against a bad edit made minutes earlier. **Folder convention:** the backup folder sits beside the tracked file, named `_backup` (underscore prefix, no other qualifier). Do not use the word `archive` — an archive implies deliberate, meaningful retention of historical versions; this is a rolling safety net whose only purpose is undoing a bad edit, not a version history to browse. - Folder: `\_backup\` - Filename pattern: `_backup_.xlsx` - Every backup file must be verified non-zero-byte immediately after creation, before the edit proceeds. If the backup fails or is zero bytes, STOP — do not make the edit. **Tool choice for the backup copy:** use PowerShell's `Copy-Item`, invoked from inside the same PowerShell script that performs the edit — not a separate `windows-mcp-*:FileSystem` copy-mode tool call. Timed comparison: in-process `Copy-Item` costs roughly 3ms (warm cache); a separate `windows-mcp-*:FileSystem` tool call costs roughly 11.5 seconds for the same copy, because every standalone tool call pays a full orchestration round-trip. **Always bundle backup + edit + save into a single PowerShell script**, never as separate sequential tool calls, so the backup is effectively free rather than a step worth skipping under time pressure. ### Verification discipline — applies every time Every write session to a tracked Excel file follows this sequence: 1. Confirm the target file exists and is non-zero before opening. 2. Take the pre-edit backup (above); confirm it is non-zero. 3. Open via COM, make the edit(s), save, close, quit, release the COM object. 4. Confirm the file's modified timestamp changed and its size is sane. 5. Re-open in a fresh, separate COM session (not the same object) and read back the edited cell(s) to confirm the write actually persisted to disk — this is the test that actually proves the round-trip works, not just that Save() didn't error. ### Project cache sidecar — how a tracker gets referenced as context without caching the binary file **The .xlsx file itself is never placed in a Project Cache staging directory.** Whatever project-level mechanism keeps key context loaded into every session is markdown/text-oriented — dropping a binary .xlsx into it breaks that pattern. Instead, the tracker gets a markdown sidecar, following the same convention already used for other non-text-native source documents (a .pdf gets a .pdf.md sidecar; an .xlsx tracker gets an .xlsx.md sidecar). **What the sidecar is:** a flat markdown table mirroring the tracker's rows and columns exactly — not a narrative summary. It exists to be read as reference context, not read top-to-bottom by a person. The sidecar is pure output — never edited directly, and edits to it are never read back into the tracker. The .xlsx is always the source of truth. **Where it lives:** beside the tracker, same folder, same base filename plus .md — e.g., `.xlsx` produces `.xlsx.md` in the same directory. **Generation trigger:** on demand, not on every edit — specifically when the host project's context/cache-refresh routine runs, and only if the tracker's on-disk modified timestamp is newer than the sidecar's. **Extraction method for the sidecar:** see FTR-12 (Markdown Sidecars) for the approved fast-extraction method for .xlsx files, since that guidance applies to any spreadsheet a project needs sidecar'd, not just Excel trackers specifically. ### Installation & merge behavior — how this combines with dependent domain features When this base feature and a domain-dependent feature that relies on it (e.g., legal discovery tracking) are both installed into a project's Agent Instructions, **they are not written up as two separate, parallel sections.** A dependent feature is documented as an extension nested under this feature's own section — not as a standalone section sitting beside it as if the two were independent capabilities. Concretely: the Agent Instructions gain one `EXCEL TRACKER` section (access method, backup convention, verification discipline — everything above). A domain feature that depends on it does not get its own top-level section duplicating or restating any of that. Instead, it appears as a labeled sub-section or `when working with [domain], additionally...` addendum nested inside the same section — schema, nomenclature, and folder structure specific to that domain, with the backup/access/verification mechanics referenced by pointer, never copy-pasted. This governs installation, not drafting — dependent specs remain separate files during development and review; the merge happens at the point a feature is actually installed into a project's live Agent Instructions. ## What this doesn't cover - Any specific column schema, dropdown values, or business meaning of a tracker's contents — that belongs in a domain-dependent feature (e.g., FTR-37, Legal Discovery Tracking). - Multi-user or concurrent-edit handling — this assumes single-writer usage (the agent, on the user's behalf, one edit session at a time). - Formula complexity beyond simple cross-sheet aggregation — for anything more complex, consult the project's general xlsx skill for LibreOffice-compatibility gotchas (untested in this Excel-COM-native context, since that skill targets a different toolchain). ## Confirm Confirm: Excel Tracker (Base Capability) is installed — an EXCEL TRACKER section now exists in admin\AGENT_INSTRUCTIONS.md covering access method, backup convention, and verification discipline. Any domain-dependent tracker feature installed later nests under this section rather than creating its own. Want to install another, or is that everything for now?