Truecourse Analyze

TrueCourse Analyze

Run architecture analysis on the current repository using TrueCourse.

Important

• Full analysis stashes any uncommitted changes, analyzes the clean working tree, then unstashes. The user's uncommitted work is preserved.
• Diff check analyzes the full working tree (including uncommitted changes — it does NOT stash) and compares the result against the last full analysis baseline. The report lists violations newly introduced and violations resolved since that baseline. Prefer diff for in-progress work where the user is iterating on changes.
• Always invoke via npx -y — without -y, npx will hang on the "Ok to proceed?" prompt whenever the user hasn't cached the latest truecourse version (which happens every time we publish a new release).
• LLM rules cost tokens. Never pass --llm without first relaying the token estimate to the user and getting approval. See the LLM flow below.

Instructions

1. Pick mode

Ask the user whether they want a full analysis or a diff check. If they said "diff" in their request, default to diff.

• Full: npx -y truecourse analyze
• Diff: npx -y truecourse analyze --diff

2. Decide on LLM rules

LLM rules add higher-value insights but cost tokens per run. Ask the user one question: "Run LLM-powered rules this time?" If the user is unsure, offer to run deterministic-only first (no tokens, fast) and add LLM later.

• If user approves LLM: append --llm to the command.
• If user declines LLM or wants a free run: append --no-llm.

You MUST pass either --llm or --no-llm — running without either in a non-interactive shell will exit with an error naming the flags.

3. Run the command

Use the Bash tool. This is long-running (minutes, especially with --llm) — use a timeout of at least 600000ms (10 minutes).

4. Summarize

When the command finishes, read the printed summary and relay the key numbers:

• Full analyze: one line with the total violation count and per-severity breakdown, e.g. 15 violations (2 critical, 5 high, 8 medium).
• Diff analyze: Changed files: N (X modified, Y new, Z deleted) and Summary: N new issues, N resolved. If you see ⚠ Results may be stale — baseline analysis has changed., surface that warning to the user and suggest running a full npx -y truecourse analyze to refresh the baseline.
• If the command errored, relay the error message.

5. Next steps

Tell the user they can:

• Run /truecourse-list to see the full violation list.
• Run /truecourse-fix to apply suggested fixes.

If the run was a full analyze on main (not a feature branch, not --diff), also suggest committing .truecourse/LATEST.json:

git add .truecourse/LATEST.json && git commit -m "refresh truecourse baseline"

That's the baseline --diff and the pre-commit hook read. Committing it on main lets fresh clones and git worktree add checkouts use the hook without re-running analyze. Don't suggest this on feature branches — LATEST.json updates from multiple PRs will conflict on a large generated JSON.

Source: truecourse-ai/truecourse — distributed by TomeVault.