ai-mentor-update

AI Mentor Update

You are a content maintenance tool for the ai-mentor plugin. Your job is to keep the goal and approach files structurally consistent, factually accurate, and up to date.

All paths below are relative to the repo root.

Modes

Interactive (default): follow the steps as written, asking the user at each decision point.

Non-interactive (--auto): when $ARGUMENTS contains --auto, never ask a question and never wait for input — there is no user present (this mode runs headless in CI). Parse from the arguments:

• --auto <steps> — comma-separated step numbers to run, using the Step headings below (2 = structural audit, 3 = content verification, 4 = process new changelogs, 5 = plugin catalog sync), e.g. --auto 4,5
• --files N — Step 3 scope: process the N oldest-verified files (default: 5)

The routine weekly run is --auto 4,5: process new changelogs and sync the plugin catalog. Steps 2 and 3 are deeper audits for occasional use — Step 2 largely duplicates the CI gate, and Step 3 re-verifies old content that changelog processing doesn't touch.

Auto-mode overrides, in addition to skipping every question below:

• Step 2: apply only unambiguous structural fixes (broken separator, wrong field order); report anything requiring judgment instead of fixing it. Note: CI also runs the catalog lint (go -C tools/catalog-lint run .) as a deterministic gate — prefer reporting over creative fixing.
• Step 3: process the N oldest-verified files with no per-file pause. Apply only changes that meet the "Recommended changes" bar (official-tier source + direct quote); list everything else under "needs manual verification" in the report without applying it.
• Step 4: process every digest not yet in the ledger; same evidence bar as Step 3; always append the ledger row for each processed digest.
• Step 5: apply additions and removals directly — the GitHub API response is authoritative.
• Never run git commit, git push, or create branches — the calling workflow owns git.
• Final output: end with a single markdown report (the caller uses it as a PR body) with two sections: Changes applied (file, change, source URL, supporting quote) and Not applied (finding + why it needs a human). If nothing changed, say so explicitly.

Step 1 — Setup

Run date +%Y-%m-%d via bash to establish today's date.

Then ask the user which steps to run. The menu numbers are the Step headings below — the same numbers --auto uses, so "4" means the same thing interactively and in CI:

Which maintenance steps do you want to run?

2. Structural audit — check all files against templates, cross-references, staleness
3. Content verification — web-search claims in files against current tool docs
4. Process new changelogs — incorporate what's-new digests not yet listed in processed-changelogs.md
5. Plugin catalog sync — check claude-plugins-official for new or removed plugins not yet reflected in marketplace.md or the promoted approaches/tools/

You can pick any combination (e.g. "all", "2 and 4", "just 5"). The routine pass is 4 and 5; the others are occasional deep audits.

Wait for the user's response, then run the selected steps in order. (Auto mode: skip the question — the steps come from --auto.)

Step 2 — Structural audit

Skip this step if the user did not select it.

Read templates/technique.md (technique deep-dives — prose files under approaches/techniques/) and templates/record.md (flat records — pure YAML-frontmatter files under approaches/tools/) from this skill's directory for the two approach-file structures; the playbooks-table structure is specified inline below.

Playbook files

For each per-goal file in skills/mentor/playbooks/:

• *Last verified: YYYY-MM-DD* on line 2
• One playbooks/<slug>.md file per goal in problem-mode.md's classification table (and no extras)
• Each file: a **Hidden gem:** line naming an approach that appears in its rows, and a ranked shortlist with sequential numbering, at least 3 rows, and approach links that resolve
• Row content: "Best when" is one short clause; "Why it fits" is one sentence of goal-specific judgment — flag rows that have drifted into generic filler
• The shortlist is curated, not exhaustive: top picks plus the hidden gem. Every technique file must still be ranked by at least one playbooks file (the audit's orphan check)

Technique files

For each technique deep-dive in skills/mentor/approaches/techniques/:

Section order check — verify these sections exist in this order:

1. # [Title]
2. *Last verified: YYYY-MM-DD* (line 2)
3. ## What It Is
4. ## Why It Works
5. ## When to Use It
6. ## When NOT to Use It
7. ## How It Works
   • ### Basic (Beginner)
   • ### Composing with Other Approaches (Intermediate)
   • ### Advanced Patterns
8. ## Common Pitfalls
9. ## Real-World Example — optional; kept only where the example embeds exact syntax not shown elsewhere in the file. When present it sits between Common Pitfalls and Sources.
10. ## Sources (at least one entry, each a markdown link with a one-line description)
11. ## Signals (both a - Setup: and a - Session: line; — for a tier with no signal)

Line count check — flag files under 40 lines.

No sub-sections in Basic — ### Basic (Beginner) should not contain bold sub-headers acting as sub-sections.

Record files and the index

For the flat record files in skills/mentor/approaches/tools/ (pure YAML frontmatter — kind: plugin, integration, or doc; the filename is its id) and the marketplace directory (marketplace.md):

• Records: valid ----delimited YAML with a last_verified: YYYY-MM-DD field; free-text values double-quoted. Techniques and playbooks keep the *Last verified:* line-2 marker (*Last synced* for the plugin catalog)
• approaches/index.md is generated — never hand-edit it. After changing playbooks rows, a technique's ## Signals section, or a record file, run go -C tools/approaches-index run . and commit the regenerated file (CI fails on a stale index)
• Every record (any kind) is a ranked row in at least one playbooks table and carries NO inline goals:/best_when: — both derive from its rows. Capability lines (**Plugins:**/**Built-ins:**/**Integrations:**) are forbidden: the ranking is the only routing surface
• Built-in slash commands have no records at all — each lives inside its covering technique deep-dive (/code-review et al. in built-in-review-skills, /goal+/loop in autonomous-loops, /schedule in scheduled-agents, /init in project-memory)
• Every kind: plugin record has no marketplace.md row (promotion removes the directory row)

The Go audit (go -C tools/catalog-lint run .) enforces all of this deterministically — run it first; this checklist explains its failures.

Cross-references

• Every ranked-row link (../approaches/techniques/<name>.md or ../approaches/tools/<name>.md) in goal files must point to an existing file.
• Every approach file must be referenced by at least one goal file.
• Report orphan and missing approach files.

Staleness

• Parse *Last verified: YYYY-MM-DD* (techniques, playbooks) and last_verified: (records) from every file.
• Flag files with a date older than 90 days from today.

Output

Present the audit results:

## Audit Results

- Goals: N files, N issues
- Approaches: N files, N issues
- Cross-references: N orphans, N missing
- Staleness: N files older than 90 days

### Issues
[List each issue with file path, issue type, and details]

If there are structural issues, ask the user whether to fix them now or continue. Apply confirmed fixes before proceeding. (Auto mode: apply only unambiguous fixes, report the rest.)

Step 3 — Content verification

Skip this step if the user did not select it.

Ask the user:

Verify all files or a specific one?

• All files — check every goal and approach file (oldest-reviewed first)
• Specific file — enter a path, e.g. approaches/plan-mode.md, or playbooks/<goal>.md for one goal's rankings

Wait for the user's response. (Auto mode: skip the question — process the --files N oldest-verified files.)

For each file in scope, use web search to verify claims against current tool documentation. Target official sources: tool documentation, changelogs, GitHub releases, official blogs.

For approach files, check:

• Feature accuracy: Does Claude Code actually support what's described? Has the feature been renamed, changed, or removed?
• Command syntax: Are CLI commands, flags, and slash commands still correct?
• Missing features: Are there significant new Claude Code features related to this approach that the file doesn't mention?
• "How It Works" accuracy: Are the step-by-step instructions still correct?

For the goal routing files (playbooks/<goal>.md), also check:

• Rankings: Is the most broadly useful approach ranked first per goal?
• Hidden gems: Does each still name the most non-obvious high-value approach, present in its section's rows?
• Missing approaches: Cross-check against all approach files — is any relevant approach missing from a goal's shortlist?
• Misplaced approaches: Are any rows a poor fit for their goal?

Output

For each file with issues:

### [filename] — NEEDS UPDATE
- [what's wrong] → [proposed fix] (source: [URL])

Ask the user which fixes to apply. For each confirmed fix, edit the file — and because this step verifies the file's claims against current docs, update its *Last verified* date to today.

If processing all files, ask after each file whether to continue to the next one or stop. (Auto mode: no per-file pause; apply Recommended-bar fixes directly and collect the rest for the report.)

Step 4 — Process new changelogs

*Skip this step if the user did not select

Content truncated.