When should I use substitute-eraser?

substitute-eraser is useful in the following scenarios: • Automated Technical Debt Audit: Scan the entire repository to identify forgotten TODOs and FIXMEs, categorizing them by severity to prioritize refactoring efforts. • Pre-Merge Quality Gate: Integrate into CI/CD pipelines to detect critical placeholders or temporary stubs in production-bound code, preventing incomplete features from being merged. • Project Management Sync: Automatically convert detected code placeholders into actionable tasks for platforms like GitHub Issues or Linear, streamlining the transition from code-level notes to tracked work items. • Documentation and Configuration Cleanup: Audit non-code files such as READMEs and config files for stale example values or 'xxx' placeholders to maintain professional documentation standards.

substitute-eraser

from plurigrid

This skill should be used when the user asks to "scan for TODOs", "find placeholders", "clean up stubs", "remove temporary code", "audit for incomplete code", or "erase substitutions from codebase". Scans existing files for placeholder tokens and generates remediation plan.

⭐1stars🔀2forks📁View on GitHub🕐Updated Jan 9, 2026

When & Why to Use This Skill

Substitute Eraser is a specialized codebase auditing tool designed to identify and manage technical debt. It scans source code, configurations, and documentation for placeholder tokens like TODO, FIXME, and temporary stubs. By generating detailed remediation plans and severity-based reports, it helps developers ensure code completeness and prevents temporary or 'mock' code from leaking into production environments, significantly improving code hygiene and maintainability.

Use Cases

Automated Technical Debt Audit: Scan the entire repository to identify forgotten TODOs and FIXMEs, categorizing them by severity to prioritize refactoring efforts.
Pre-Merge Quality Gate: Integrate into CI/CD pipelines to detect critical placeholders or temporary stubs in production-bound code, preventing incomplete features from being merged.
Project Management Sync: Automatically convert detected code placeholders into actionable tasks for platforms like GitHub Issues or Linear, streamlining the transition from code-level notes to tracked work items.
Documentation and Configuration Cleanup: Audit non-code files such as READMEs and config files for stale example values or 'xxx' placeholders to maintain professional documentation standards.

name	substitute-eraser
description	This skill should be used when the user asks to "scan for TODOs", "find placeholders", "clean up stubs", "remove temporary code", "audit for incomplete code", or "erase substitutions from codebase". Scans existing files for placeholder tokens and generates remediation plan.
version	0.1.0
trit	-1
color	"#6B26D8"
role	validator
- skill-creator	○ structure
- accept-no-substitutes	⊖ pattern library
- code-review	⊖ remediation format

name

substitute-eraser

description

version

0.1.0

trit

-1

color

"#6B26D8"

role

validator

- skill-creator

○ structure

- accept-no-substitutes

⊖ pattern library

- code-review

⊖ remediation format

Substitute Eraser

Scan existing codebases for placeholder tokens. Generate remediation plan.

Purpose

Audit existing files for substitution tokens (TODO, FIXME, placeholder, mock, etc.) and produce actionable remediation plan. Distinct from accept-no-substitutes which validates agent output.

Scope: Existing Files

This skill scans what already exists:

Source code files
Configuration files
Documentation with stale placeholders
Test fixtures that leaked into production

Complements accept-no-substitutes (output validation).

Trit Assignment

Trit: -1 (MINUS/VALIDATOR)
Hue: 270° (violet - deep scan)
Role: Codebase auditor, technical debt detector

Scan Workflow

1. Discovery

# Scan current directory
just substitute-scan .

# Scan specific path
just substitute-scan src/

2. Classification

Severity	Tokens	Action
CRITICAL	TODO, FIXME, placeholder, xxx	Must fix before merge
WARNING	mock-, fake-, stub-* (outside tests)	Review context
INFO	example_, demo_	Document or remove

3. Remediation Report

Output format:

SUBSTITUTE ERASER REPORT
========================
Scanned: 142 files
Found: 23 substitutions

CRITICAL (7):
  src/auth.py:42      TODO: implement token refresh
  src/api.py:118      placeholder value
  src/db.py:55        FIXME: race condition
  ...

WARNING (12):
  src/service.py:30   mock_client (not in test file)
  ...

INFO (4):
  README.md:15        example_config
  ...

REMEDIATION PLAN:
1. [CRITICAL] src/auth.py:42 - Implement token refresh logic
2. [CRITICAL] src/api.py:118 - Replace placeholder with actual value
...

Context-Aware Exceptions

Acceptable Locations

Pattern	Acceptable In
`mock-`, `fake-`, `stub-*`	`_test.py`, `test_.py`, `/tests/`
`example_*`	`README.md`, `/docs/`, `/examples/`
`demo_*`	`/demo/`, documentation
`TODO`	Issue tracker references with ID

Exception Syntax

Mark intentional placeholders:

# SUBSTITUTE-OK: mock used for test isolation
mock_client = MockHTTPClient()

Commands

# Full scan with report
just substitute-scan <path>

# Critical only (CI mode)
just substitute-critical <path>

# Generate remediation tasks
just substitute-tasks <path> --output=github  # GitHub issues
just substitute-tasks <path> --output=linear  # Linear tickets
just substitute-tasks <path> --output=todo    # TODO file

# Interactive fix mode
just substitute-fix <path>

Integration with GF(3)

Operates as MINUS (-1) in audit triads:

substitute-eraser(-1) + code-generator(+1) + review-coordinator(0) = 0

Emits rejection signal when scan finds violations above threshold.

Additional Resources

Reference Files

references/patterns.md - Detection regex patterns (shared with accept-no-substitutes)
references/remediation.md - Fix strategies per token type

Scripts

scripts/scan.py - Main scanning script
scripts/report.py - Report generation