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:

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

---

Data sources (defaults)

Override via env vars:

---

Audit goals (what “accurate” means)

A) Board hygiene (Tasks.md)

B) Project completeness (Flatnotes)

For each active project in `SYS Workspace - Project Registry`:

- `PJT <slug> - 00 Overview`

- `PJT <slug> - 10 Research`

- `PJT <slug> - 20 Plan`

- `PJT <slug> - 90 Log`

- 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:

- preferably a short note in the project log (`PJT <slug> - 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.)

---

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:>=<date>" --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:

- 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

---

Bundled code