/north-star-review — Read aspirations, compute gaps, emit suggestions

When invoked, run .claude/scripts/north_star_review.py and present the ranked output to the user.

Step 1: Run the review

py -3 ".claude/scripts/north_star_review.py" --project <project-name>

Defaults: if no --project argument is provided, the script discovers every project under .claude/north-stars/ and reviews them all. To review one project, pass the project.name slot of .claude/project-profile.md as the argument.

Optional flags the user may pass after /north-star-review:

• --update — rewrite the Current gap and Suggested next steps sections of each thought file in place. Without this flag, the script only prints; the files stay untouched.
• --single <slug> — review one thought only.
• --repo-root <path> — override the codebase root used for grep (defaults to the project's known location).
• --json — machine-readable JSON output.

Step 2: Present the report

The script output already has the shape the user wants — pass it through verbatim. It lists, per active north-star:

• Title, slug, status
• Gap signals (count + concrete file paths from the anti-pattern grep)
• Suggested next steps (count + /design-first invocations to advance toward the aspiration)

Step 3: Offer the update step

After presenting the dry-run, ask via AskUserQuestion:

"Write these gap signals and suggested next steps into the thought files? (--update rewrites Current gap and Suggested next steps in each .md; the rest of each file stays verbatim.)"

If the user confirms, re-run with --update and confirm the writes landed.

Step 4: Offer to act on top suggestions

For the ranked suggestion list, ask the user via AskUserQuestion:

"Pick a suggested next step to draft now via /design-first, or skip."

Options should be the top 3 suggestions across all north-stars (one per north-star, prioritized by gap count). If the user picks one, invoke /design-first with the suggested task title — this hands off to the data-architect, which will then read the aspirations in its Step 0.5 and produce a contract that explicitly cites the north-star it advances.

Step 5: If nothing actionable, say so

When all north-stars return zero gap signals (no anti-pattern hits in the codebase), tell the user:

"All active north-stars are unblocked at the file-grep level. No anti-patterns currently in the codebase. Next move is to define richer anti-patterns OR to add feature work that ACTIVELY advances each aspiration — not remediation. Re-run after the next contract lands."

Notes on the engine

The script is fail-soft: missing CodeGraph CLI, missing repo, parse errors — all degrade gracefully and emit warnings to stderr. The script never modifies anything without --update.

What this skill does NOT do

• Does NOT create new north-stars — use /north-star "<aspiration>" for that.
• Does NOT promote a suggestion into a contract automatically — the user must invoke /design-first explicitly after picking from the suggestion list.
• Does NOT modify thought files without --update.

Periodic auto-review

The user can schedule this skill via /schedule or a CronCreate-style routine for weekly runs. The recommended cadence: weekly on Monday morning, with --update enabled so the thought files accumulate a longitudinal gap-signal history.

/schedule "Weekly north-star review" --cron "0 9 * * 1" --command "/north-star-review --update"

Output of scheduled runs lands in stdout — pair with the existing notification pipeline to surface the gap-signal changes vs the previous week.