deferred-log

Instruction file imported from aaltaay/Nova (.cursor/rules/deferred-log.mdc). Copyright stays with the author.

Deferred tracker -- mandatory for every agent

The parking lot for known bugs and parked features is GitHub Issues labeled deferred on aaltaay/Nova. DEFERRED_LOG.md is the how-to only -- do not prepend ## D-NNN sections there. Peer of PROBLEM_LOG.md -- same respect, same Lifecycle declaration, same constitution severity if you skip it after parking real work.

Browse: https://github.com/aaltaay/Nova/issues?q=is%3Aissue+label%3Adeferred

This rule applies to every agent that works in this repo -- parent Auto sessions, Cursor built-ins used on Nova work, and every Nova specialist (tester, hod-momo, market-feed, ...). There is no exception by agent type or "we were busy" framing.

Hard requirement

When a session finds a real bug it will not fix now, or parks a feature the human asked for, the agent MUST open or comment on a GitHub Issue labeled deferred in the same session (before or with the CHANGELOG / task-log / commit):

• A bug whose fix is too big, architectural, or the wrong task for this session
• A fully diagnosed root cause whose patch is deferred (do not band-aid; do not stay silent)
• A user-requested feature you declined to build now (too complicated, needs an ADR, needs a human decision)

Skipping the GitHub issue after parking real work is a constitution violation -- same severity as skipping PROBLEM_LOG.md after a real fix.

Before any fix (mandatory, every chat)

1. Run py -3 tools/deferred_log.py status (alias: priorities). That ranked list is the known-bugs / parked-features to-do. When the human asks "what's missing / what are our priorities," answer from this command -- do not invent a second tracker.
2. Search open deferred issues for the module, symptom, or keyword. If an existing issue already covers the ask: work from that issue. Honor Status (label parked means do not start it), Unblock, and Next. Do not start a parallel fix that ignores them.
3. If you are about to "improve" chart drawings, scanners, VWAP, lifespan, NEWS, or any other named row: you must cite the matching issue (#NNN, or its legacy D-NNN) or explain why this is a different bug.

Starting a fix that is already an open issue, without reading the issue, is a constitution violation -- same class as parking work with no issue.

Where and how

1. Title: a plain short title -- no D-NNN prefix, no ID to allocate. The durable id is the GitHub issue number (#NNN), minted atomically by GitHub, so concurrent agents cannot collide. D-NNN survives only as a legacy alias on the issues that already carry one.
2. Labels: always deferred, plus one of P0..P3, plus bug / enhancement (feature) / decision, plus domain:<name>. Add blocked or parked when that is the status.
3. Body fields (never optional): Kind, Severity, Effort, Why parked, Blast radius, Unblock, Next, Evidence. How-to: DEFERRED_LOG.md.
4. Do not log secrets, tokens, or personal data.
5. Cross-link from CHANGELOG / task-log Related: when those also get an entry.
6. When you later fix the entire issue: use Closes #NNN in the PR, close with reason completed, write PROBLEM_LOG.md for a bug, and set Lifecycle deferred_log=#NNN plus problem_log=.... Partial fixes use Refs #NNN, get an evidence comment, and leave the issue open.
7. py -3 tools/deferred_log.py refresh-index rewrites the offline snapshot. It is a read cache for environments without gh -- nothing allocates from it any more, so a stale snapshot degrades a listing but can no longer corrupt the tracker. Refresh it when convenient; it is not a gate.

Do not

• Dump parked work only into .cursor/agent-memory/*-memory.md Backlog (scratchpad, not SSOT)
• Dump product-phase NEXT / L-Z parking-lot work here -- that stays in Nova-Roadmap-Status.md
• Treat a CHANGELOG Follow-ups: bullet as enough -- if it is a real bug or parked feature, it belongs on a deferred issue
• Prepend a new ## D-NNN section to DEFERRED_LOG.md
• Band-aid a P0/P1 so you can skip writing the issue
• Mint a new D-NNN; the prefix is legacy-only and hand-allocating one re-opens the collision class
• Start a fix that is already an open issue without reading that issue first (honor parked / Unblock / Next)

When skip is allowed

Only for:

• You actually fixed the bug this session (that is PROBLEM_LOG.md, then deferred_log=none unless you also closed an issue)
• Purely cosmetic edits with nothing parked
• Status-only polls / read-only triage with no new gap found
• The gap is already an open issue and you did not learn anything new -- still declare deferred_log=#NNN if you touched that area, else none

When skipping, Lifecycle (specialists) or the closing report (parent) MUST say deferred_log=none, deferred_log=skipped, or deferred_log=n/a -- never silently omit the declaration.

Lifecycle declaration (specialists + parent reports that use Lifecycle)

Every Lifecycle footer MUST include:

deferred_log=<#NNN or D-NNN>|none|skipped|n/a

Example after parking a bug:

**Lifecycle:** memory=changed | promotion=none | dashboard=clean | handoff=none | task_log=knowledge/task-log/2026-08-26-example.md | problem_log=n/a | deferred_log=D-001

Relationship to other logs

Related

• .cursor/rules/problem-log.mdc
• .cursor/rules/self-annealing.mdc
• .cursor/rules/change-log.mdc
• .cursor/rules/task-log.mdc
• docs/agent-operations.md
• tools/deferred_log.py
• DEFERRED_LOG.md (how-to)