tp-guide

Guide

Read the project's current state and recommend the highest-impact next step.

Argument: [intent] (optional) — freeform text expressing a loose goal or concern (e.g., auth feels fragile, ready to ship, new to this repo).

Steps

1. Run first-run preflight per skills/_shared/first-run.md.

2. Read project docs per skills/_shared/read-project-docs.md. three-pillars-docs/vision.md is the primary filter — it tells you what this project is for, and therefore what work genuinely matters. If three-pillars-docs/vision.md is missing, the single most impactful recommendation you can make is to run /tp-setup to establish one; say so before anything else.

3. Scan active designs: Check three-pillars-docs/tp-designs/ for in-flight work. For each, read design.md (first 20 lines) and handoff.md (if present) to understand phase and status. While scanning, note whether each design's Problem/Vision alignment section is consistent with the current three-pillars-docs/vision.md — a design that drifted from the vision is a candidate for either reshaping or dropping.

4. Check completed designs: Scan three-pillars-docs/completed-tp-designs/ to understand what's already been built.

5. Read the first line of .claude/last-design if it exists, to know what the user was last working on. This file is an MRU stack — one design per line, most recent first. 4.5. Closeout nudge (read-only, fail-open): run python3 "$TP_ROOT"/skills/_shared/detect_unarchived.py --repo . --exclude {mru-top-design} --slugs-only (exclude the MRU-top design from step 4 — that's the user's own active work, not drift). Any slugs returned are designs whose three-pillars-docs/tp-designs/{slug}/ dir carries implementation evidence (implementation-audit.md / spike-results.md) but has not been archived to completed-tp-designs/ — i.e. closeout pending. Surface each in the recommendation as "closeout pending — run /tp-design-learn {slug} (or /tp-spike-learn) then /tp-design-complete {slug}", since an unarchived merged design hard-fails the framework's CI check on {default}. Non-blocking, fail-open — the helper always exits 0; a detector error yields no nudge, never an error. One detector, two surfaces: this soft nudge shares detect_unarchived.py with the hard CI check.

6. If an intent was provided, filter your analysis through that lens. For example:

   • "auth feels fragile" → focus on auth-related known issues, architecture gaps, and whether a design or spike is warranted
   • "ready to ship" → focus on blocking issues, incomplete designs, and release readiness
   • "new to this repo" → provide onboarding: what the project does (straight from three-pillars-docs/vision.md), how it's structured, how to use the TDD pipeline

7. Weigh candidates against the vision. Before recommending, score each candidate (known issue, in-flight design, roadmap item) by its connection to the vision:

   • High alignment: directly advances the vision's Problem, serves its Users, or fixes a break that blocks a Success signal. These go to the top.
   • Low alignment: solves a real technical problem but isn't load-bearing for the stated why. These get deprioritized even if they're interesting. Call out the deprioritization explicitly so the user can override it.
   • Conflict: the work pushes the project toward a stated non-goal. Recommend against it and suggest updating the vision via /tp-docs-update if the user thinks the non-goal has moved.

8. Choose the weight class. Not everything needs the full pipeline. Score the four rubric axes — risk, blast radius, reversibility, novelty (each low/medium/high; see skills/_shared/weight-class.md, or shell python3 "$TP_ROOT"/skills/_shared/weight_class.py recommend) — and match the class to the complexity: