skills.rest
jellyrock
jellyrockOFFICIAL
Explore all skills by this author →
WebsiteGitHub

tech-debt-scan

Match changed files against tech-debt inventory entries before pull requests.

37|2|Updated Jun 28, 2025
Search Tags:#git#code-review#software-engineering#pull-request#tech-debt#pre-pr#debt-sweep
One-click install
npx skills add https://github.com/jellyrock/jellyrock --skill tech-debt-scan-jellyrock
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: tech-debt-scan
Source: https://github.com/jellyrock/jellyrock/tree/main/.claude/skills/tech-debt-scan
Command: npx skills add https://github.com/jellyrock/jellyrock --skill tech-debt-scan-jellyrock

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When PR follow-ups are only mentioned in PR descriptions, they are forgotten the moment the PR merges, leading to accumulated untracked technical debt in the JellyRock codebase. This Skill enforces a deliberate pre-PR sweep of the canonical tech-debt inventory to ensure no existing debt is accidentally left unresolved and all new deferred work is properly recorded.

Core Features & Use Cases

  • Existing Debt Matching: Automatically identifies tech-debt entries in docs/architecture/tech-debt.md that overlap with files changed in the current PR branch.
  • Guided Classification: Walks users through each matched entry, letting them mark it as resolved, still applicable, deferred further, or a false positive.
  • New Debt Capture: Helps draft and add new structured tech-debt entries for work explicitly deferred by the PR, with stable slugs for cross-referencing.
  • Verification & Cross-Linking: Runs doc linting to confirm anchor references remain valid after changes, and sets up follow-up links for PR bodies.

Quick Start

Run the tech-debt-scan skill before opening a pull request for any non-trivial code change to surface relevant existing tech debt entries and capture any new deferred work for tracking.

Frequently Asked Questions about tech-debt-scan

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I track technical debt deferred in a pull request after merge?▼

Tracking technical debt deferred in a pull request requires recording deferred work in a canonical inventory file like docs/architecture/tech-debt.md before merge, preventing follow-ups mentioned only in PR descriptions from being lost after merge.

What is a pre-PR tech debt sweep and when do I need it?▼

A pre-PR tech debt sweep matches changed feature branch files against existing entries in a tech-debt inventory file. You need it before opening a pull request for any non-trivial code change to surface relevant existing debt entries and capture newly deferred work for tracking.

How do I scan a feature branch for existing tech debt entries before opening a pull request?▼

To scan a feature branch for existing tech debt entries, match the changed files against structured entries in docs/architecture/tech-debt.md. The process walks you through each matched entry to classify it as resolved, still applicable, deferred further, or a false positive.

Does this tech debt sweep work with a standard git pull request workflow?▼

Yes, the tech debt sweep works with a standard git pull request workflow by analyzing feature or fix branches before the PR is opened. It enforces the mandate that all PR follow-ups must be recorded in the tech-debt file to maintain an accurate audit trail of known issues.

Why should I record PR follow-ups in a tech-debt file instead of just the pull request description?▼

Recording PR follow-ups in a tech-debt file instead of only the pull request description prevents them from being forgotten the moment the PR merges. This maintains an accurate audit trail of known issues and prevents accumulated untracked technical debt in the codebase.

Can I cross-link tech-debt entries in the PR body using stable slugs?▼

Yes, you can cross-link tech-debt entries in the PR body using stable slugs. The scan helps draft new structured tech-debt entries with stable slugs for cross-referencing and runs doc linting to confirm anchor references remain valid after changes.

Related Skills

Explore More Software Engineering Skills→
rocky2431rocky2431
11

syncing-docs

Sync specs and architecture docs with code and decisions.

Community
Basic
Dev10x-GuruDev10x-Guru
7

Dev10x:gh-pr-doctor

Audit merged GitHub Pull Requests for unresolved review threads and create follow-up issues.

Official
Intermediate
PLeVasseurPLeVasseur

fls-changelog-verification

Compare spec diffs against src/changelog.rst entries and map changed paragraph IDs to :dp: anchors.

Community
Intermediate
GDSDNGDSDN
3

po-manage-story-backlog

Add, update, and review story backlog items with prioritization and status tracking.

Community
Advanced