project-insights

name

project-insights

description

Reviews project-level operational hygiene: INSIGHTS.md triage, CLAUDE.md gap checks, and documentation-maintenance follow-ups (including .ai-notes -> .reference promotion candidates). Checks the global skills directory and both project + global CLAUDE.md to determine what has been implemented, what remains open, and what is stale. Use this whenever the user says "project insights", "review insights", "project hygiene review", "project maintenance review", "clean up insights", "which INSIGHTS items are still relevant", "triage my insights backlog", or asks for a periodic docs/process cleanup pass.

Project Insights — Triage & Archive

Goal

Help the user keep INSIGHTS.md lean and actionable. Check what's been implemented, what's genuinely still open, and what's gone stale — then confirm with the user section by section before making any changes.

---

Step 1 — Gather context

Read these files in order:

1. INSIGHTS.md in the current project directory — the items to triage
2. Project CLAUDE.md — to check whether CLAUDE.md gap items have been filled
3. Global agent CLAUDE.md — to check whether items were promoted there already
4. Skills directory listing — to check whether skill candidates/upgrades exist:

ls /

If no global skills directory is configured, skip that check and continue with
project-local evidence.

For **Skill Upgrade** items, go one step further: read the relevant skill's `SKILL.md` briefly to check whether the described improvement is actually present (not just that the skill exists).

For **Automation Ideas** that mention a specific script or alias, check the shell aliases file or the relevant scripts directory.

Also check lightweight docs hygiene signals:
- `.reference/INDEX.md` exists and includes newly promoted files.
- `.reference` docs touched in recent work have updated `Last reviewed`.
- `.reference` metadata includes `Purpose`, `When to use`, `Source of truth`, `Owner`, `Confidence`, `Last reviewed`.
- Reusable docs in `.ai-notes` are flagged as promotion candidates.

---

## Step 2 — Triage each item

Go through every non-archived item in INSIGHTS.md and assign one status:

| Status | Meaning |
|--------|---------|
| ✅ Done | The improvement exists — skill built, CLAUDE.md updated, script implemented, issue resolved |
| ⏳ Open | Not yet implemented, still clearly relevant |
| 📤 Promote to global CLAUDE.md | A project-level CLAUDE.md gap that's universal enough to belong in the global CLAUDE.md |
| 🗑️ Stale | No longer relevant — project direction changed, different approach taken, or won't fix |

**Checking Skill Candidates:** look for a matching directory name in the global skills directory. If it exists, confirm it covers what the INSIGHTS item described.

**Checking Skill Upgrades:** find the skill, read its SKILL.md, look for whether the improvement described in the INSIGHTS item is present. Don't require exact wording — judge by intent.

**Checking CLAUDE.md Gaps:** search project CLAUDE.md and global CLAUDE.md for the described content. A gap is "filled" if the relevant information is now present somewhere — the fact that it ended up in a different section than expected is fine.

**Checking Automation Ideas:** if the idea mentioned a specific script, alias, or tool, check whether it exists. If it's vague ("we should automate X"), lean toward ⏳ Open unless there's clear evidence it was addressed.

---

## Step 3 — Present sections one at a time and wait for replies

**Critical rule: present ONE section, then stop and wait for the user's reply before showing the next section. Never output multiple sections in the same response.**

Item types to label:
- `[Skill]` — new skill to build
- `[Skill Upgrade]` — add/change in an existing skill
- `[CLAUDE.md]` — add to project CLAUDE.md
- `[Automation]` — script or alias to create

Work through sections in this order:

### Section 1 — ✅ Done (present first, then STOP)

Output only this section:

INSIGHTS Triage — [Project Name] — [Today's Date]

✅ Done — safe to archive (N)

1. [Item name] — [what confirms it's done]
2. [Item name] — [what confirms it's done] ...

→ Reply with numbers (e.g. 1, 3), all, or skip

Then stop. Wait for the user's reply. Do not output the next section.

---

### Section 2 — 🗑️ Stale (only after Section 1 reply received)

Once the user replies to Section 1, output only:

🗑️ Stale — suggest archiving (N)

1. [Item name] — [why no longer relevant] ...

→ Reply with numbers (e.g. 1, 3), all, or skip

Then stop. Wait for the user's reply. Do not output the next section.

---

### Section 3 — 📤 Global CLAUDE.md (only after Section 2 reply received)

Once the user replies to Section 2, output only:

📤 Worth promoting to global CLAUDE.md (N)

1. [Item name] — [why this is universal, not project-specific] ...

→ Reply with numbers (e.g. 1, 3), all, or skip

Then stop. Wait for the user's reply. Do not output the next section.

---

### Section 4 — ⏳ Still open (only after Section 3 reply received)

Once the user replies to Section 3, output only:

⏳ Still open — keep (N)

1. [Skill] [Item name] — [why still relevant]
2. [Skill Upgrade] [Item name] — [what needs adding]
3. [CLAUDE.md] [Item name] — [what section it belongs in]
4. [Automation] [Item name] — [what to build] ...

Health: [ratio of done to open, any pattern worth noting]

→ Any to remove entirely? Reply with numbers or skip

After the user replies to Section 4, apply all confirmed changes (Step 4).

---

### Section 5 — 🔁 Repeatable Maintenance Tasks (always include)

After Section 4 is confirmed, provide a short repeatable maintenance checklist:

🔁 Repeatable maintenance tasks

1. [Monthly] Review .ai-notes for promotion candidates to .reference.
2. [Monthly] Reconcile .reference/INDEX.md with actual files.
3. [When touched] Update Last reviewed in edited .reference docs.
4. [Quarterly] Archive stale INSIGHTS items and refresh open ones.

→ Add any of these as TODO tasks? Reply with numbers, all, or skip

---

## Step 4 — Apply confirmed changes

### Archiving items (✅ Done and 🗑️ Stale)

Move confirmed items from their section into the `## 🗃️ Archive` section at the bottom of INSIGHTS.md. Format:

```markdown
### ✅ [Item name] — [confirmed done / stale / promoted] — [YYYY-MM-DD]
[One sentence: what was found or why archived]

Remove the original entry from its section. If a section becomes empty, leave the section header — it may get new entries later.

Promoting to global CLAUDE.md (📤)

Add a concise, actionable note to the global CLAUDE.md under the most relevant existing section. Keep it to 1-3 sentences — global CLAUDE.md is a quick reference, not a journal. If no section fits, create a minimal new one.

After promoting, archive the INSIGHTS item as "promoted to global CLAUDE.md".

---

Notes on judgment calls

• Skill exists but doesn't cover the improvement: mark as ⏳ Open, note the gap specifically.
• Item is vague and hard to verify: lean Open, flag it as "needs clarification".
• Item references a project phase that's now complete: lean Stale.
• Item duplicates something already in CLAUDE.md or SESSION.md gotchas: mark Done — information being present is what matters, not where it landed.