Help us improve
Share bugs, ideas, or general feedback.
From runesmith-devtools
Scan the workspace for stale, orphaned, or unreferenced artifacts using a cross-reference graph (plans → refs/tickets/decisions → research/source-docs/drafts). Identifies what is ACTUALLY tech debt - content that no longer traces back to a live plan, ticket, or decision. Workspace-side only; never enters source repos. Use after a round of changes, when things feel messy, proactively between work sessions, or to verify cleanliness before a release. Triggers on: "tech debt", "clean up", "stale files", "what's out of date", "is anything orphaned".
npx claudepluginhub runemarklabs/runesmith --plugin runesmith-devtoolsHow this skill is triggered — by the user, by Claude, or both
Slash command
/runesmith-devtools:tech-debthaikuThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Identify workspace content that is no longer alive - orphaned, unreferenced, or superseded - and propose archive/delete actions with user consent.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Share bugs, ideas, or general feedback.
Identify workspace content that is no longer alive - orphaned, unreferenced, or superseded - and propose archive/delete actions with user consent.
Tech debt here means unreferenced content, not just old content. Age is a weak signal; cross-references are the real test. A 6-month-old reference doc still cited by an active plan is alive. A 1-week-old draft that nobody points to and references a superseded plan is debt.
Scope is the workspace only. This skill does not touch source repos. For code-level tech debt (unused functions, dead classes, leftover scaffolding from refactors), see runesmith-cc:code-tech-debt - a CC-side skill template deployed by runesmith-cc:bootstrap-cc.
agents/workspace-scanner.md - subagent for directory walk + raw findingslib/folder-conventions.md - canonical layout this skill scans againstlib/user-prompts.md - structured-input requirement for any user promptThis skill follows the marketplace-wide user-prompt standard in lib/user-prompts.md. Every user prompt MUST use the host client's structured input UI. Never freeform plain-text yes/no.
No pre-flight checks needed. This is a read-only scan until the user consents to act on findings.
Use for:
/runesmith-workspace:reallocate to verify nothing fell throughDo not use for:
/runesmith-cc:code-tech-debt deployed inside {PROJECT}.cc/<repo>/)/runesmith-workspace:reallocate)Tech-debt never enters {PROJECT}.cc/<repo>/. The CC head's repos are CC's territory. The workspace's job ends at the boundary.
Tech-debt does scan {PROJECT}.cc/comms/archive/ if asked (rare - archive is the audit trail, usually preserved).
Walk the canonical workspace dirs and build an in-memory graph:
Nodes (the things that can be alive or dead):
plans/active/<slug>/ plan + its decisions.md + refs/<file> + tickets/<id>.jsonplans/archive/<YYYY-MM>/<slug>/ plannotes/<file>.mddrafts/{features,project-docs,bugs}/<slug>/ draftresearch/<topic>/<file>source-docs/<topic>/<file>archive/superseded/<YYYY-MM>/<entry>archive/tickets-pushed/<YYYY-MM>/<KEY>.jsonarchive/_pre-*/<ISO>/plugins/<plugin>/ (for marketplace dev workspaces)Edges (the references that keep nodes alive):
plan.md cites refs/<file>.md in its References section → that ref is referencedtickets: array → those Jira keys are referenced (the archived JSON in archive/tickets-pushed/<YYYY-MM>/<KEY>.json is alive as history)decisions.md mentions another plan slug → that plan is referencedsupersedes: field → the superseded plan is referenced (as a history pointer)notes/<file>.md content mentions a plan slug or draft slug → that slug is referenced{PROJECT}.cc/comms/open/ content mentions a plan slug → that plan is referencedLiveness rules:
status: open | building | blocked plan = ALIVEstatus: done | superseded plan in plans/active/ = should-be-archived (debt: structural)plans/archive/ = preserved history, not debtToggle for cached graph:
--cached flag (structured prompt option "Use cached graph if available"): read graph from archive/_workspace-index/<ISO>.json if present and less than 24 hours old; else rebuild and cache.For each node, assign a status:
status: done plan still in plans/active/, pushed ticket draft still in plans/active/<slug>/tickets/)supersedes: from a newer plan; preserve as historyarchive/_pre-*/ snapshot older than 90 days.claude-plugin/plugin.json, ticket JSON whose plan slug doesn't exist)Workspace tech debt scan ({N} nodes, {M} edges)
Structural debt (wrong location)
plans/active/old-rewrite/ status: done → plans/archive/2026-05/old-rewrite/?
plans/active/api-v2/tickets/draft-001.json pushed as PROJ-42 → archive/tickets-pushed/2026-05/?
Orphans (no live references)
research/edge-comparison/ last referenced never → archive/superseded/2026-05/research-edge-comparison/?
drafts/features/billing-old/ references superseded plan billing-v1 → archive/superseded/2026-05/draft-billing-old/?
source-docs/vendor-api-v0/ consumed by archived plan api-v1 → archive/superseded/2026-05/source-vendor-api-v0/?
notes/2025-12-15-thoughts.md no slug mentions, >90 days old → archive/superseded/2026-05/notes/?
Operation snapshots (stale)
archive/_pre-migration/2026-01-15T.../ > 90 days → safe to delete
archive/_pre-cc-bootstrap/2026-02-03T.../ > 90 days → safe to delete
Broken
plans/active/orphan-tickets/tickets/draft-007.json plan dir doesn't exist → route via inbox?
plugins/runesmith-broken/ missing .claude-plugin/plugin.json → fix or remove?
Alive (informational)
{N} active plans, {M} live refs, {P} draft slugs in-flight
Surface a structured multi-pick:
What do you want to act on?
[ ] Structural debt (move to canonical location)
[ ] Orphans (archive to archive/superseded/<YYYY-MM>/)
[ ] Operation snapshots > 90 days (delete)
[ ] Broken items (review individually)
[ ] Nothing - preview only
Then per selected category, a per-item structured prompt or batch-confirm.
Trigger phrase ("clean up", "archive them", "apply") gates the destructive moves per lib/consent.md.
Per approved row:
archive/_pre-tech-debt/<ISO>/ before any move or delete--cached was used✓ Workspace tech debt addressed
Snapshot: archive/_pre-tech-debt/<ISO>/
Resolved: {N} items
- structural debt: {n}
- orphans archived: {n}
- operation snapshots deleted: {n}
- broken items: {n} fixed, {n} surfaced for manual review
Workspace state: {clean | needs review | major-debt}
Live graph: {N} active plans, {M} references, {O} orphans remaining
lib/folder-conventions.md taxonomy{PROJECT}.cc/<repo>/archive/_pre-tech-debt/<ISO>/ before any move or deletestatus: done plan to archive) handled here, not duplicating reallocate's jobrunesmith-cc:code-tech-debtNo tech debt found: "Workspace is clean. {N} active plans, {M} alive references, 0 orphans."
Reference graph fails to build: Surface the path that broke, abort the scan, suggest running /runesmith-workspace:reallocate first if structure is non-canonical.
Orphan's content suggests it might still be relevant: Surface the head + filename; ask user to confirm orphan status before archive (don't auto-archive content with recent edits or referenced filenames in headers).
Plan slug referenced by note but plan doesn't exist: Flag the note as having a stale reference; surface for user to update.
Cache exists but is older than 24 hours: Rebuild silently; offer to use cache anyway via structured prompt if user wants fast preview.
reallocate does one-shot structural migration (initialize / restructure / normalize). tech-debt does ongoing hygiene within the canonical structure. Some overlap is intentional:
If a workspace fails both checks (non-canonical AND has orphans), run reallocate first, then tech-debt.