joplin-llm-wiki: Skill for Cursor

Detect drift between a Spectra change and the current codebase state. Reports time dormancy, broken design anchors, task collisions with external commits, and a single recommended next command.

Input: Optionally specify a change name (e.g., /spectra-drift add-auth). If omitted, infer from conversation context or auto-select if only one active change exists.

Prerequisites: This skill requires the spectra CLI. If any spectra command fails with "command not found" or similar, report the error and STOP.

Steps

1. Determine change name

   If not provided, infer from context or run spectra list --json to auto-select. If multiple active changes exist and no name is given, list candidates and ask the user to rerun with an explicit name.

2. Run programmatic drift analysis

   spectra drift <change-name> --json
   

   The JSON contains:

   • severity: "light" / "medium" / "heavy"
   • total_score: aggregate over Time / Structure / Tasks (Environment is display-only)
   • dimensions: array of { kind, status, score, contributes_to_total }
   • broken_anchors: design.md references (file paths / symbols / functions / CLI flags) that no longer resolve
   • tasks_blocked_external: pending tasks whose referenced files were modified by commits outside the change dir
   • tasks_maybe_resolved: pending tasks whose verb+target keywords match commit subjects since created
   • primary_recommendation: a single copy-pasteable command line

3. Present the report

   Use a user-readable, conclusion-first format. The first substantive paragraph after the title MUST be a plain-language conclusion that says what to do next before showing score tables, broken anchors, task collisions, or severity labels.

   Translate severity into action-oriented meaning:

   • Light: the change can continue with apply.
   • Medium: the change can continue, but the plan should be refreshed before implementation.
   • Heavy: the old plan is likely unsuitable for direct implementation; restart or refresh first.

   Recommended shape:

   ## Drift Report: <change-name>
   
   <Plain-language conclusion. Example for medium: "This change can continue, but update the plan before implementing it. Related code has changed since the plan was written, so applying the old tasks directly may cause rework or conflicts.">
   
   ### Why
   
   - <1-3 plain-language reasons derived from dimensions, broken anchors, and task collisions>
   
   ### Details
   
   | Item              | Result                                                 |
   | ----------------- | ------------------------------------------------------ |
   | Time              | <status>                                               |
   | Design references | <broken anchor count or "No broken references">        |
   | Pending tasks     | <blocked/maybe-resolved count or "No task collisions"> |
   | Overall           | <light/medium/heavy, total score N>                    |
   
   ### Recommendation
   
   Run `<primary_recommendation>`.
   

   Keep technical details below the plain-language conclusion. List broken anchors, blocked tasks, and maybe-resolved tasks only when non-empty. Omit empty technical detail sections entirely. Keep the report short enough to skim; the goal is to help the user decide, not to explain the scoring model.

4. Apply the recommendation interactively

   Use the AskUserQuestion tool to offer one decision based on severity. Use plain-language option labels while preserving the exact command in each option description. Do NOT auto-invoke /spectra-apply, /spectra-ingest, or spectra archive; always wait for the user's choice.

   • Light (score 0-3, drift is minor):
     • Recommended label: "Directly start work"
       • Description: run /spectra-apply <name>
     • Alternate label: "Pause for now"
       • Description: do nothing until the user reviews manually
   • Medium (score 4-8, refresh worth doing):
     • Recommended label: "Refresh the plan"
       • Description: run /spectra-ingest <name> with the broken references and task collisions as context
     • Alternate label: "Directly start work"
       • Description: run /spectra-apply <name> only if the user knows the reported changes are harmless
     • Alternate label: "Pause for now"
       • Description: do nothing until the user reviews manually
   • Heavy (score >8 or anchor decay >30%, design diverges from code):
     • Recommended label: "Archive and restart"
       • Description: run <primary_recommendation>
     • Alternate label: "Refresh the plan"
       • Description: try /spectra-ingest <name> before restarting
     • Alternate label: "Pause for now"
       • Description: do nothing until the user reviews manually