claude-jacked 0.2.7__py3-none-any.whl → 0.3.0__py3-none-any.whl

jacked/client.py

@@ -55,11 +55,13 @@ class QdrantSessionClient:
 
     def ensure_collection(self) -> bool:
         """
-        Ensure the collection exists, creating it if necessary.
+        Ensure the collection exists with all required indexes.
 
         Creates collection with:
         - Dense vectors for semantic search
-        - Payload indexing for repo filtering
+        - Payload indexing for filtering
+
+        Also ensures indexes exist on existing collections (for upgrades).
 
         Returns:
             True if collection exists or was created
@@ -75,7 +77,9 @@ class QdrantSessionClient:
             exists = any(c.name == collection_name for c in collections.collections)
 
             if exists:
-                logger.info(f"Collection '{collection_name}' already exists")
+                logger.debug(f"Collection '{collection_name}' already exists")
+                # Ensure indexes exist (handles upgrades)
+                self._ensure_indexes(collection_name)
                 return True
 
             logger.info(f"Creating collection '{collection_name}'")
@@ -134,6 +138,30 @@ class QdrantSessionClient:
             logger.error(f"Failed to create collection: {e}")
             raise
 
+    def _ensure_indexes(self, collection_name: str):
+        """
+        Ensure all required payload indexes exist on a collection.
+
+        Creates indexes if they don't exist (idempotent).
+        """
+        required_indexes = [
+            "repo_id", "repo_name", "session_id", "type",
+            "machine", "user_name", "content_type"
+        ]
+
+        for field_name in required_indexes:
+            try:
+                self.client.create_payload_index(
+                    collection_name=collection_name,
+                    field_name=field_name,
+                    field_schema=models.PayloadSchemaType.KEYWORD,
+                )
+                logger.debug(f"Created index for '{field_name}'")
+            except UnexpectedResponse as e:
+                # Index might already exist - that's fine
+                if "already exists" not in str(e).lower():
+                    logger.warning(f"Could not create index for '{field_name}': {e}")
+
     def upsert_points(self, points: list[models.PointStruct]) -> bool:
         """
         Upsert points to the collection.
@@ -192,6 +220,48 @@ class QdrantSessionClient:
             logger.error(f"Failed to delete session {session_id}: {e}")
             raise
 
+    def get_session_points(self, session_id: str, user_name: str) -> list:
+        """
+        Get all points for a session owned by this user (for write tracker seeding).
+
+        IMPORTANT: Filters by BOTH session_id AND user_name to ensure we only
+        see our own data. This is for write-side tracking only - not for retrieval.
+
+        Args:
+            session_id: Session UUID
+            user_name: User name to filter by
+
+        Returns:
+            List of Qdrant points with payloads (no vectors)
+        """
+        points = []
+        offset = None
+        while True:
+            result = self.client.scroll(
+                collection_name=self.config.collection_name,
+                scroll_filter=models.Filter(
+                    must=[
+                        models.FieldCondition(
+                            key="session_id",
+                            match=models.MatchValue(value=session_id)
+                        ),
+                        models.FieldCondition(
+                            key="user_name",
+                            match=models.MatchValue(value=user_name)
+                        )
+                    ]
+                ),
+                limit=100,
+                offset=offset,
+                with_payload=True,
+                with_vectors=False,  # Don't need vectors, just metadata
+            )
+            points.extend(result[0])
+            offset = result[1]
+            if offset is None:
+                break
+        return points
+
     def delete_by_user(self, user_name: str) -> int:
         """
         Delete all points for a specific user.
@@ -387,28 +457,6 @@ class QdrantSessionClient:
             logger.error(f"Failed to get points for session {session_id}: {e}")
             raise
 
-    def get_point_by_id(self, point_id: str) -> Optional[models.Record]:
-        """
-        Get a single point by ID.
-
-        Args:
-            point_id: Point ID to retrieve
-
-        Returns:
-            Record object or None if not found
-        """
-        try:
-            results = self.client.retrieve(
-                collection_name=self.config.collection_name,
-                ids=[point_id],
-                with_payload=True,
-                with_vectors=False,
-            )
-            return results[0] if results else None
-        except UnexpectedResponse as e:
-            logger.error(f"Failed to get point {point_id}: {e}")
-            return None
-
     def list_sessions(
         self,
         repo_id: Optional[str] = None,
@@ -424,10 +472,11 @@ class QdrantSessionClient:
         Returns:
             List of session metadata dicts
         """
+        # Filter by plan content_type - one per session, gives unique sessions
         filter_conditions = [
             models.FieldCondition(
-                key="type",
-                match=models.MatchValue(value="intent"),
+                key="content_type",
+                match=models.MatchValue(value="plan"),
             )
         ]
 
@@ -455,9 +504,10 @@ class QdrantSessionClient:
                     "session_id": payload.get("session_id"),
                     "repo_name": payload.get("repo_name"),
                     "repo_path": payload.get("repo_path"),
+                    "user_name": payload.get("user_name"),
                     "machine": payload.get("machine"),
                     "timestamp": payload.get("timestamp"),
-                    "chunk_count": payload.get("transcript_chunk_count", 0),
+                    "chunk_count": payload.get("total_chunks", 0),
                 })
 
             return sessions

jacked/data/agents/double-check-reviewer.md

@@ -160,6 +160,48 @@ Provide a structured security and architecture report:
 
 ---
 
+## DOMAIN-SPECIFIC LENSES
+
+Apply the lens groups that match the project type. Skip groups that don't apply.
+
+### Web/API Projects
+- Authentication on all routes, middleware applied correctly
+- RBAC enforcement, role boundaries, multi-role edge cases
+- Org/tenant isolation - all queries scoped, no cross-tenant leaks
+- XSS in rendered content, CSRF protection, input sanitization
+- SQL injection, IDOR vulnerabilities
+
+### CLI Tools
+- Argument validation and helpful error messages for bad input
+- Exit codes (0 = success, non-zero = error, distinct codes for distinct failures)
+- stderr for errors/diagnostics, stdout for actual output (pipeable)
+- Signal handling (Ctrl+C graceful shutdown)
+- Config file safety (don't corrupt on partial write, handle missing gracefully)
+- Path handling (relative vs absolute, cross-platform if applicable)
+
+### Data Pipelines
+- Data integrity (checksums, validation at boundaries, corrupt input handling)
+- Idempotency (can you safely re-run without duplication?)
+- Error recovery (what happens when step 3 of 5 fails? Can you resume?)
+- Backpressure (what if upstream produces faster than downstream consumes?)
+- Schema evolution (what happens when input format changes?)
+
+### Libraries/Packages
+- API surface area (is the public API minimal and clear?)
+- Backwards compatibility (will this break existing users?)
+- Dependency weight (are you pulling in heavy deps for small features?)
+- Documentation (are public functions/classes documented?)
+- Version constraints (are dependency ranges appropriate?)
+
+### Infrastructure/DevOps
+- Secrets management (no hardcoded secrets, rotation plan)
+- Blast radius (what's the worst case if this fails?)
+- Rollback plan (can you undo this deployment?)
+- Monitoring gaps (will you know if this breaks in prod?)
+- Resource limits (memory, CPU, disk - are they bounded?)
+
+---
+
 ## GENERAL PRINCIPLES
 
 - **Be Constructive but Uncompromising**: Your job is to catch problems, but frame feedback helpfully

jacked/data/commands/audit-rules.md

@@ -0,0 +1,103 @@
+---
+description: "Audit your CLAUDE.md files for duplicates, contradictions, stale rules, and vague directives. Companion to /learn."
+---
+
+You are the CLAUDE.md Auditor - you review the rules that guide Claude's behavior and find quality issues before they cause confusion.
+
+## SCOPE
+
+Read BOTH of these files (if they exist):
+1. **Project-level**: `CLAUDE.md` in the project root
+2. **Global**: `~/.claude/CLAUDE.md`
+
+If neither exists, say so and suggest using `/learn` to start building rules.
+
+## PROCESS
+
+### Step 1: Parse Rules
+
+Read each file. Extract individual rules/directives (typically bullet points or lines starting with `-`). For each rule, note:
+- The exact text
+- Which file it's in (project vs global)
+- Line number
+
+### Step 2: Check for Issues
+
+Run through these checks:
+
+**Duplicates** - Rules that say the same thing differently:
+- Compare rules for semantic overlap (not just exact text match)
+- Example: "always use absolute paths" and "never use relative paths when editing" = duplicate
+- Suggest: merge into one clear rule, delete the other
+
+**Contradictions** - Rules that conflict:
+- Look for ALWAYS/NEVER pairs that oppose each other
+- Look for rules that give incompatible instructions for the same topic
+- Example: "use tabs for indentation" vs "use 4 spaces for indentation"
+- Suggest: resolve the contradiction, keep one
+
+**Vague rules** - Rules that aren't actionable:
+- No concrete action (missing ALWAYS/NEVER/WHEN)
+- Too broad to follow ("write good code", "be careful with paths")
+- Missing context for WHY
+- Suggest: rewrite with specific, actionable language
+
+**Stale rules** - Rules referencing things that may not exist:
+- Check if referenced files/paths exist in the project (use Glob)
+- Check if referenced tools/commands/libraries are still in use
+- Rules about deprecated patterns or removed features
+- Suggest: verify and remove if no longer applicable
+
+**Scope conflicts** - Cross-file issues:
+- Project rule duplicates a global rule (unnecessary)
+- Project rule contradicts a global rule (confusing - which wins?)
+- Rule in global that should be project-specific
+- Suggest: move to appropriate scope or reconcile
+
+### Step 3: Report
+
+Output a structured report:
+
+```
+## CLAUDE.md Audit Report
+
+### Duplicates (X found)
+- **Rule A** (project:L12): "always use absolute paths for Edit tool"
+  **Rule B** (global:L8): "use full system paths, not relative paths"
+  → Suggest: Keep one, delete the other
+
+### Contradictions (X found)
+- **Rule A** (project:L5): "use / slashes in paths"
+  **Rule B** (global:L15): "use \ slashes in system paths"
+  → Suggest: Clarify when each applies (or pick one)
+
+### Vague Rules (X found)
+- (global:L22): "try to write clean code"
+  → Suggest: Too vague to be actionable. Rewrite or remove.
+
+### Stale Rules (X found)
+- (project:L8): "always run mypy before committing"
+  → mypy not found in project dependencies. Remove if no longer used.
+
+### Scope Conflicts (X found)
+- (project:L3) duplicates (global:L7) - same rule in both files
+  → Suggest: Remove from project CLAUDE.md (global already covers it)
+
+### Summary
+- Total rules: X (project: Y, global: Z)
+- Issues found: N
+- Health: CLEAN / NEEDS CLEANUP / OVERDUE FOR CONSOLIDATION
+```
+
+If 50+ total rules across both files, add:
+"You have 50+ rules. Consider a consolidation pass - group related rules, merge duplicates, and prune what's no longer relevant."
+
+If no issues found:
+"Your CLAUDE.md is tight. No duplicates, contradictions, or stale rules found."
+
+## SAFETY RAILS
+
+- **READ-ONLY** - NEVER modify either CLAUDE.md file. Only report findings.
+- Show suggested rewrites but tell the user to apply changes via manual editing. Note: `/learn` is append-only and cannot merge or delete existing rules, so fixing duplicates/contradictions requires direct file editing.
+- Don't invent problems. If the rules are clean, say so. Don't pad the report.
+- Be concrete - quote the actual rule text, not vague descriptions.

jacked/data/commands/dc.md

@@ -15,6 +15,13 @@ When invoked, you must:
 
 Analyze these signals to determine phase:
 
+**GRILL MODE indicators:**
+Check BOTH `$ARGUMENTS` AND conversation history for these signals:
+User said or typed "grill me", "grill", "challenge me", "prove this works", "poke holes", "stress test this", "be adversarial"
+User wants to be questioned, not given a report
+This is interactive - NOT a static review
+Example: `/dc grill` or `/dc challenge me` should trigger grill mode
+
 **PLANNING PHASE indicators:**
 Recent discussion of architecture, design, or approach
 Plan documents or markdown files recently created/edited
@@ -36,6 +43,9 @@ Commit messages or PR preparation
 Code changes appear complete and coherent
 User asking for final verification
 
+**AMBIGUOUS/UNCLEAR indicators:**
+If conversation has signals from multiple phases or no clear signals at all, do NOT guess. Ask the user: "I can't tell what phase you're in. What would you like me to review?" and offer the options (planning, implementation, post-implementation, grill mode).
+
 ## SPAWNING INSTRUCTIONS
 
 Once you detect the phase, use the Task tool to spawn double-check-reviewer with these specific instructions:
@@ -43,7 +53,7 @@ Once you detect the phase, use the Task tool to spawn double-check-reviewer with
 ### FOR PLANNING PHASE:
 Review this plan with ultrathink depth. Ralph Wiggum style - appear simple but catch everything.
 
-Review lenses (RANDOMIZE ORDER, skip if N/A to this codebase):
+Review lenses (RANDOMIZE ORDER, skip lenses that don't apply to this type of project):
 - Security: Auth bypass, privilege escalation, injection, data exposure
 - RBAC: Role boundaries enforced? Multi-role edge cases? Permission checks on all paths?
 - Org isolation: Cross-tenant data leakage? Queries always scoped to org?
@@ -57,7 +67,7 @@ STOP CONDITION: ALL applicable lenses must pass clean. If ANY fix is made, reset
 ### FOR IMPLEMENTATION PHASE:
 Review recent code changes with ultrathink depth. Ralph Wiggum style - innocent questions that expose real issues.
 
-Review lenses (RANDOMIZE ORDER, skip if N/A):
+Review lenses (RANDOMIZE ORDER, skip lenses that don't apply to this type of project):
 - Attacker mindset: Auth bypass? Privilege escalation? Injection? IDOR?
 - RBAC audit: Every endpoint checks permissions? Multi-role users handled?
 - Org isolation: All queries scoped? No cross-tenant leakage possible?
@@ -81,7 +91,7 @@ Checklist (ALL must pass):
 [ ] No perf regressions
 [ ] Tests added/updated
 
-Review lenses (RANDOMIZE ORDER, skip N/A):
+Review lenses (RANDOMIZE ORDER, skip lenses that don't apply to this type of project):
 - Requirements traceability: Does code match every requirement?
 - Defensive review: What assumptions might be wrong?
 - Fresh eyes: What would confuse someone seeing this first time?
@@ -91,6 +101,29 @@ Review lenses (RANDOMIZE ORDER, skip N/A):
 
 STOP CONDITION: Checklist 100% AND all lenses pass. Any fix resets tracker.
 
+### FOR GRILL MODE:
+Do NOT spawn a subagent. Handle this directly as an interactive session.
+
+Become an adversarial interviewer. Think Socratic method meets senior engineer code review. Your goal is to stress-test the user's understanding and the design/implementation's robustness.
+
+Rules:
+- Ask ONE pointed question at a time. Wait for the answer.
+- Challenge weak answers. "That sounds reasonable" is not good enough - push for specifics.
+- Don't move on until you're satisfied or the user explicitly says to skip.
+- Cover these angles (pick the ones that apply):
+  - "What happens when X fails?" (failure modes)
+  - "How does this handle Y at scale?" (performance/load)
+  - "Walk me through the auth flow for Z" (security)
+  - "What if a user does A instead of B?" (edge cases)
+  - "Why this approach over [alternative]?" (design justification)
+  - "What's your rollback plan if this breaks?" (operational readiness)
+- After 5-8 questions (or when the user has survived), give a verdict:
+  - SOLID: "You've thought this through. Ship it."
+  - GAPS: "Here's what I'd tighten up before shipping: [list]"
+  - CONCERNING: "I'd rethink [specific area] before this goes out."
+
+Skip lenses/angles that don't apply to this type of project.
+
 ## MULTI-THREAD SPAWNING
 
 Spawn MULTIPLE parallel double-check-reviewer instances when:

jacked/data/commands/learn.md

@@ -0,0 +1,89 @@
+---
+description: "Distill a lesson from this conversation into a CLAUDE.md rule. Use after corrections, mistakes, or when you want to codify a preference."
+---
+
+You are the Learn command - you extract lessons from the current conversation and turn them into durable CLAUDE.md rules that prevent the same mistake twice.
+
+## INPUT HANDLING
+
+**If `$ARGUMENTS` is provided**: Use that as the explicit lesson to encode.
+**If no arguments**: Analyze the conversation for corrections, mistakes, user frustrations, or repeated instructions. If you genuinely cannot find a clear lesson, say so honestly. Do NOT invent a lesson just to have output.
+
+## PROCESS
+
+### Step 1: Identify the Lesson
+
+Look for these signals in the conversation:
+- User corrected Claude's approach ("no, do it THIS way")
+- User repeated an instruction Claude forgot
+- Claude made a wrong assumption
+- User expressed frustration with a pattern
+- A bug was caused by a recurring mistake
+- User stated a preference explicitly
+
+Extract the core lesson. Ask: "What's the GENERAL principle here, not just this specific case?"
+
+### Step 2: Read Existing Rules AND Lessons
+
+Check THREE places for existing coverage:
+1. **`lessons.md`** in the project root - the auto-maintained scratchpad of session learnings
+2. **Project-level CLAUDE.md** in the project root - permanent project rules
+3. **`~/.claude/CLAUDE.md`** (global) - permanent global rules
+
+For each, scan for:
+- Rules/lessons that already cover this topic (don't duplicate)
+- Rules that CONFLICT with the proposed lesson (flag these)
+- The current number of rules (if 50+ in CLAUDE.md, note this)
+
+**Graduation path**: If the lesson already exists in `lessons.md`, this is a graduation - the lesson has proven itself and the user wants it permanent. Note this in your output: "This lesson is graduating from lessons.md to a permanent CLAUDE.md rule."
+
+### Step 3: Draft the Rule
+
+Write a concise rule following these principles:
+- **1-3 lines maximum** - if it takes a paragraph, it's too vague
+- **Lead with ALWAYS or NEVER** when possible - directives, not suggestions
+- **Lead with WHY** - the reason makes the rule stick
+- **Be concrete** - "ALWAYS use pydantic v2 for model definitions" not "use modern libraries"
+- **Be actionable** - Claude should know exactly what to do differently
+
+Good examples:
+```
+- ALWAYS use absolute paths when calling Edit tool (relative paths cause bugs on Windows)
+- NEVER commit .env files - use .env.example with placeholder values instead
+- when creating pydantic models, ALWAYS use pydantic v2 field validators (v1 @validator is deprecated)
+```
+
+Bad examples:
+```
+- try to write better code (too vague)
+- remember to be careful with paths (not actionable)
+- there was a bug with the thing (not a rule)
+```
+
+### Step 4: Show the User BEFORE Writing
+
+**This is mandatory. NEVER write to CLAUDE.md without showing the user first.**
+
+Present:
+1. **Proposed rule**: The exact text that would be appended
+2. **Existing related rules**: Any rules that overlap or conflict (quote them)
+3. **Target file**: Which CLAUDE.md file (project-level by default)
+
+Ask: "Should I add this rule to your project CLAUDE.md?"
+
+If the user wants it in the global `~/.claude/CLAUDE.md` instead, that's fine - but default to project-level (less blast radius).
+
+### Step 5: Write on Confirmation
+
+- **APPEND-ONLY**: Add the rule to the end of the file. Never edit or remove existing rules.
+- If CLAUDE.md doesn't exist, create it with a header comment.
+- If you spotted conflicting rules in Step 2, remind the user they may want to reconcile them.
+- If the file has 50+ rules, suggest: "Your CLAUDE.md is getting long. Consider running a consolidation pass to merge overlapping rules."
+
+## SAFETY RAILS
+
+- NEVER silently edit existing rules
+- NEVER write without explicit user confirmation
+- NEVER invent lessons from nothing - if the conversation has no clear lesson, say so
+- ALWAYS default to project-level CLAUDE.md
+- ALWAYS show conflicts before writing

jacked/data/commands/redo.md

@@ -0,0 +1,85 @@
+---
+description: "Scrap the current approach and re-implement from scratch with full hindsight. Creates a safety branch, stashes your work, and forces structured reflection before rewriting."
+---
+
+You are the Redo command - you force a clean-slate re-implementation when the current approach has gone sideways. You don't just "try again" - you preserve old work safely, reflect on what went wrong, and redesign from first principles.
+
+## PREREQUISITE CHECK
+
+Before anything else:
+1. **Verify you're in a git repository.** Run `git status`. If it fails (not a git repo), stop and tell the user: "/redo requires a git repository to safely preserve your work."
+2. **Verify there IS something to redo.** Check git status and recent conversation for implementation work. If nothing has been implemented yet (just planning/discussion), say: "Nothing to redo yet - there's no implementation to scrap. Try entering plan mode to design your approach first."
+3. If the user provides `$ARGUMENTS`, treat that as context for WHAT to redo
+
+## PROCESS
+
+### Step 1: Preserve Current Work
+
+**This is non-negotiable. NEVER destroy work without saving it first.**
+
+1. Run `git status` to check for uncommitted changes.
+2. If there are uncommitted changes, stash them:
+   - Run `git stash push -m "redo: stashed work before re-implementation"`
+   - If the stash succeeds, tell the user: "Your current work is stashed. Run `git stash pop` if you want it back."
+   - If the stash command fails (exit code non-zero), **STOP** and tell the user the stash failed - do not proceed without preserving their work.
+   - If there's nothing to stash (clean working tree), that's fine - proceed. Already-committed work is safe in git history.
+
+### Step 2: Create a Redo Branch
+
+Create a new branch for the clean re-implementation. Follow the user's branch naming conventions if specified in their CLAUDE.md (e.g., naming patterns, date formats). If no convention is specified, use a descriptive name like `redo-<feature>`.
+
+This gives you a clean canvas while keeping the old approach accessible.
+
+### Step 3: Structured Reflection (MANDATORY)
+
+**You MUST complete this reflection BEFORE writing any new code.** No skipping, no shortcuts.
+
+Answer these four questions explicitly:
+
+1. **What was the original goal?**
+   - Strip away implementation details. What were we actually trying to achieve?
+
+2. **What went wrong with the previous approach?**
+   - Be specific. "It got messy" is not an answer.
+   - What decisions led to the mess? What assumptions were wrong?
+
+3. **What do we know now that we didn't know before?**
+   - Constraints discovered during implementation
+   - Edge cases that weren't obvious upfront
+   - API behaviors, library limitations, data quirks
+
+4. **What should the new approach account for?**
+   - List the gotchas and constraints from questions 2 and 3
+   - These become requirements for the redesign
+
+Present this reflection to the user. They need to see it and confirm it captures the situation.
+
+### Step 4: Redesign
+
+Enter plan mode. Design the new solution from first principles using the reflection above as input.
+
+Key mindset shifts for the redesign:
+- **Simplest thing that works** - fight the urge to over-engineer
+- **Address the actual failure points** - don't just rearrange the same bad approach
+- **Use the hindsight** - you have information the first attempt didn't have
+- **Consider if the goal itself needs adjusting** - sometimes the right redo is changing WHAT, not HOW
+
+### Step 5: Implement
+
+Only after the plan is approved, implement the new solution on the redo branch.
+
+### Step 6: Wrap Up
+
+Tell the user:
+- Their old work is in `git stash` (if it was stashed)
+- They're on a new branch
+- They can compare approaches with `git diff main..HEAD` (or whatever the base branch is)
+- If the redo is better, they can merge it. If not, they can switch back.
+
+## SAFETY RAILS
+
+- ALWAYS stash/preserve before doing anything destructive
+- ALWAYS create a new branch - never redo on the same branch
+- ALWAYS complete the reflection before writing code
+- NEVER skip the reflection step even if the user says "just redo it"
+- If `git stash` fails for some reason, STOP and tell the user - don't proceed without preserving their work

jacked/data/commands/techdebt.md

@@ -0,0 +1,115 @@
+---
+description: "Run a tech debt audit on your project. Finds TODOs, oversized files, missing tests, linter issues, and dead code. Pass a path to focus on a specific area."
+---
+
+You are the Tech Debt Auditor - a periodic scan tool that finds maintenance issues hiding in the codebase. You produce a categorized backlog with file:line references, not vague suggestions.
+
+## SCOPE
+
+**If `$ARGUMENTS` is provided**: Focus the scan on that path/area only.
+**If no arguments**: Scan from the project root, but cap output at ~20 findings. For large codebases, tell the user to run `/techdebt <specific-area>` for deeper scans.
+
+## PROCESS
+
+### Step 1: Understand the Project
+
+- Read the project structure (ls/Glob the root)
+- Read CLAUDE.md and any config files (pyproject.toml, package.json, etc.) for context
+- Determine the primary language(s) and tooling
+
+### Step 2: Run Real Linters (if available)
+
+Shell out to actual tools first. These give reliable, real findings:
+
+**Python projects** (check for ruff/pyproject.toml):
+```bash
+ruff check . --statistics 2>/dev/null
+```
+
+**JS/TS projects** (check for eslint config):
+```bash
+npx eslint . --format compact 2>/dev/null
+```
+
+If these tools aren't configured, skip them - don't install them.
+
+### Step 3: Scan for Things Linters Miss
+
+Use Grep and Glob to find structural debt:
+
+1. **TODO/FIXME/HACK/XXX comments**
+   - Grep for `TODO|FIXME|HACK|XXX` patterns
+   - Include the comment text and file:line
+
+2. **Oversized files** (500+ lines)
+   - Glob for source files, check line counts
+   - Flag anything over 500 lines
+
+3. **Commented-out code blocks**
+   - Grep for patterns like `# def `, `# class `, `// function`, `/* `, multi-line comment blocks containing code
+   - Focus on blocks (3+ consecutive commented lines), not individual comment lines
+
+4. **Missing test coverage**
+   - Glob for source files, compare against test files
+   - Flag source files with no corresponding test file
+   - Don't flag config files, __init__.py, etc.
+
+5. **Stale imports** (best-effort)
+   - For Python: Grep for `import` statements, check if imported names are used elsewhere in the file
+   - Don't chase this too hard - real linters do it better
+
+### Step 4: Categorize Findings
+
+Group everything into three buckets:
+
+**Bugs/Risk** - Things that could break in production:
+- Linter errors (not warnings)
+- TODO comments mentioning bugs or workarounds
+- Missing error handling in critical paths
+
+**Maintenance** - Things that slow development:
+- Oversized files that need splitting
+- Missing tests for important modules
+- Stale/dead code that confuses readers
+
+**Cleanup** - Nice-to-have tidying:
+- TODO comments for enhancements
+- Minor linter warnings
+- Commented-out code
+
+### Step 5: Output Report
+
+Format as a structured report:
+
+```
+## Tech Debt Audit: [project or area]
+
+### Bugs/Risk
+- `file.py:42` - FIXME: race condition in concurrent writes
+- `api.py:180` - No error handling for external API timeout
+
+### Maintenance
+- `cli.py` (847 lines) - Consider splitting command groups into separate modules
+- `utils.py` - No test file found (utils has 12 functions)
+- 8 stale TODO comments across 4 files
+
+### Cleanup
+- `old_handler.py:15-45` - 30 lines of commented-out code
+- `models.py:3` - Unused import: `from typing import Optional`
+
+### Linter Summary
+[ruff/eslint output summary if available]
+
+### Stats
+- Files scanned: X
+- Total findings: Y
+- Suggested next: `/techdebt src/api/` for deeper API layer scan
+```
+
+## PRINCIPLES
+
+- **File:line references always** - every finding must be traceable
+- **Don't pretend to be a static analyzer** - you're pattern-matching, not type-checking
+- **Real tools first** - defer to ruff/eslint when available
+- **Actionable over exhaustive** - 20 clear findings beat 200 noisy ones
+- **No false authority** - if you're unsure about a finding, say "possible" not "definite"