Flatnotes + Tasks.md GitHub Audit

---

name: flatnotes-tasksmd-github-audit description: "Thoroughly audit Tasks.md + Flatnotes for drift and accuracy; use GitHub (gh CLI) as source of truth to detect stale notes/cards and missing links. Produces a report and an optional fix plan."

---

Flatnotes + Tasks.md + GitHub Audit

Use this skill when Brandon asks to audit the Flatnotes/Tasks.md system for accuracy and ensure it’s up to date, using GitHub as the source of truth.

Quick start

Run the bundled auditor (report-only):

node skills/flatnotes-tasksmd-github-audit/scripts/audit.mjs --since-days 30 --write

Outputs:

Markdown report: tmp/flatnotes-tasksmd-audit.md

JSON report: tmp/flatnotes-tasksmd-audit.json

> If gh is not authenticated, the audit still runs but GitHub checks will be marked as SKIPPED_GITHUB.

---

Data sources (defaults)

Tasks.md root: /home/ds/.config/appdata/tasksmd/tasks

Flatnotes root: /home/ds/.config/appdata/flatnotes/data

Flatnotes “system notes” mirror in workspace: notes/resources/flatnotes-system/

Override via env vars:

TASKS_ROOT

FLATNOTES_ROOT

---

Audit goals (what “accurate” means)

A) Board hygiene (Tasks.md)

Global lanes exist: 00 Inbox, 05 Backlog, 10 Next, 20 Doing, 30 Blocked, 40 Waiting, 90 Done.

Lane rule preference: prio-p2 lives in 05 Backlog by default (no prio-p2 in 10 Next).

Doing WIP ≤ 3 (preference).

Cards should be consistently formatted (Outcome/Steps) and tagged (proj/prio/eff/type).

Blocked cards include Unblock:.

Project cards include a Flatnotes pointer (Flatnotes: ...).

B) Project completeness (Flatnotes)

For each active project in SYS Workspace - Project Registry:

Required project notes exist:

- PJT - 00 Overview - PJT - 10 Research - PJT - 20 Plan - PJT - 90 Log

Hub note has:

- Current status (1–3 bullets) - Links section with repo + Tasks filter - Decisions section linking relevant ADR(s)

C) GitHub truth reconciliation (GitHub = source of truth)

For each project repo in the registry:

Open PRs should have a corresponding Tasks card (Doing/Next/Blocked/Waiting) OR an explicit reason why not.

Recently merged PRs should be reflected somewhere:

- preferably a short note in the project log (PJT - 90 Log) + hub status update, or - a Done card with PR link. - (Audit treats either as reconciled; it may warn if a merged PR is only on a Done card but missing from the log.)

Done cards should ideally include a PR link when work was shipped via PR.

---

Workflow (recommended)

1) Parse registry - Read SYS Workspace - Project Registry from Flatnotes. - Extract: slug, status, Tasks tag, GitHub repo URL.

2) Scan Tasks.md - Index cards by lane and by proj-* tag. - Flag lane rule violations (prio-p2 in Next, etc.). - Flag cards missing Flatnotes pointer.

3) Scan Flatnotes - Check required project notes exist. - Check hub Decisions section links ADR notes.

4) GitHub cross-check - Use gh: - gh pr list --state open --json ... - gh pr list --state merged --search "merged:>=" --json ... (or equivalent) - Try to match PRs ↔ Tasks cards using: - PR URL in card content - PR number - Title substring heuristic

5) Report - Output: summary + per-project drift list + fix plan.

---

Applying fixes (guardrails)

Default is report-only.

If Brandon explicitly asks to apply fixes:

Safe auto-fixes allowed:

- create missing Flatnotes notes (10 Research, etc.) using existing templates - add missing ADR links to hub Decisions section - move prio-p2 from Next → Backlog - add missing Flatnotes pointers to Tasks cards

Anything that renames files or deletes content: ask first.

---

Bundled code

scripts/audit.mjs — generates the report (Markdown + JSON). If needed, patch it rather than rewriting.

Run the bundled auditor (report-only):

node skills/flatnotes-tasksmd-github-audit/scripts/audit.mjs --since-days 30 --write

Outputs:

Markdown report: tmp/flatnotes-tasksmd-audit.md

JSON report: tmp/flatnotes-tasksmd-audit.json

> If gh is not authenticated, the audit still runs but GitHub checks will be marked as SKIPPED_GITHUB.

---