substitute-eraser

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.

16 stars

byplurigrid

View on GitHub Installation ↓

Best use case

substitute-eraser is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Teams using substitute-eraser should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/substitute-eraser/SKILL.md --create-dirs "https://raw.githubusercontent.com/plurigrid/asi/main/plugins/asi/skills/substitute-eraser/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/substitute-eraser/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How substitute-eraser Compares

Feature / Agent	substitute-eraser	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# 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
```bash
# 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:
```python
# SUBSTITUTE-OK: mock used for test isolation
mock_client = MockHTTPClient()
```

## Commands

```bash
# 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

Related Skills

We are still matching the closest adjacent skills for this page. In the meantime, continue through the full directory.