Skip to content
sdlc

T-QIBD-audit-memoizes-parsed-frontmatter

Status: closed/done · Impact: low · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to ready before picking up.

Goal

Section titled “Goal”

audit_entities.py parses every entity’s frontmatter twice — once per file in the main per-file audit, and again inside collect_depends_on_graph when building the cycle-detection adjacency. The corpus is tiny today so it does not matter, but the structural waste is in the hot path of every future /sdlc:entities-audit invocation. Closing this gap is a one-line refactor that future-proofs the audit before someone notices it as a slow command.

Cited by T-J2CW-add-epic-entity-task-depends-on-dependencies.

Today

Section titled “Today”

From the originating post-mortem:

audit_entities.py re-parses every task file inside collect_depends_on_graph because FileReport doesn’t carry the parsed frontmatter forward. Acceptable today (corpus is tiny), but worth memoizing if the audit ever grows to thousands of entries.

Script: plugin/scripts/audit_entities.py. Look for collect_depends_on_graph and the FileReport dataclass / structure.

Proposed

Section titled “Proposed”

collect_depends_on_graph reads parsed frontmatter from the existing FileReport (or whatever carrier object the per-file pass returned) rather than re-opening and re-parsing each file from disk. After the change, an audit run touches each file’s bytes exactly once.

Approach

Section titled “Approach”
  1. Inspect audit_entities.py for the structure that carries per-file audit results. Add a frontmatter (or similar) attribute that captures the already-parsed mapping.
  2. Update collect_depends_on_graph (and any other multi-pass consumer that re-parses) to read from the carrier instead of re-opening the file.
  3. Run plugin/skills/entities-audit/tests/run_evals.py and confirm all eval cases still pass.

Files to touch

Section titled “Files to touch”
  • plugin/scripts/audit_entities.py — extend FileReport (or equivalent) to carry parsed frontmatter; switch collect_depends_on_graph to consume it.

Acceptance criteria

Section titled “Acceptance criteria”
  • AC-1: plugin/skills/entities-audit/tests/run_evals.py continues to pass after the refactor.
  • AC-2: A single audit run opens each entity file at most once (verified by, e.g., instrumenting the file open or a structural code review).

Out of scope

Section titled “Out of scope”
  • Performance tuning beyond the duplicate parse (e.g. parallelizing file reads).
  • Changes to the audit’s reporting shape.

Dependencies

Section titled “Dependencies”
  • none

Discovery context

Section titled “Discovery context”

Spawned by /sdlc:task-work post-mortem of T-J2CW-add-epic-entity-task-depends-on-dependencies on 2026-05-19.

Post-mortem

Section titled “Post-mortem”

Captured by /sdlc:task-work on 2026-05-19. PR: pending.

Acceptance criteria coverage

Section titled “Acceptance criteria coverage”
  • AC-1: auto — python3 plugin/skills/entities-audit/tests/run_evals.py reports 7/7 eval case(s) passed both before and after the refactor.
  • AC-2: agent-manual — structural code review of audit_entities.py confirms only one entity-instance file-open site (audit_file at the call to path.read_text(encoding="utf-8")); the other read_text is for schema templates, not entity instances. collect_depends_on_graph no longer reads files at all — it consumes the cached report.frontmatter mapping.

What worked

Section titled “What worked”
  • The task spec was precise enough that the refactor required zero design judgment — the carrier object, the consumer, and the contract (every file opened at most once) were named explicitly.
  • The eval suite gave a fast pre/post baseline, and re-running it confirmed behaviour was preserved in seconds.

Friction and automation gaps

Section titled “Friction and automation gaps”
  • The task-work skill’s Step 4 mandates mise trust && just setup-worktree, but this repo has no justfile — the command fails noisily and the skill has no graceful fallback. The skill should detect “no justfile / no lefthook” and skip the setup step rather than asking the implementer to absorb the error and decide whether it matters.
  • This repo also has no just full-check or just ci targets, so Step 7’s “quality gate” reduces to “run the eval suite manually”. The skill assumes a project-level meta-CI that does not always exist; a per-project quality-gate config (or a task-work --no-just flag) would make Step 7 honest.
  • node_path in collect_depends_on_graph is reconstructed from report.path after the refactor — an absolute Path is rebuilt for every task with depends_on. A small follow-up could push the absolute path onto FileReport directly so cross-file passes never recompute it, but that’s a micro-optimisation and almost certainly not worth a dedicated task.

← Back to Tasks