stubbing-temporary-comments

name: stubbing-temporary-comments description: Plans changes by inserting structured temporary stub comments and then replacing them with real code in a second pass. Use for complex features, multi-file refactors, or when the user asks to plan implementation directly in code before writing full logic. license: MIT compatibility: Works best in repositories with git and ripgrep (rg) available for cleanup checks.

Stubbing Temporary Comments

Plans first in code with structured stubs, then implements in a second pass without losing intent.

Announce at start: "I'm using the stubbing-temporary-comments skill to do a comment-first implementation pass, then replace stubs with code."

When To Use

Use this skill when the task benefits from separating design from coding overhead:

• New features that touch multiple files or layers
• Refactors with uncertain implementation details
• Requests like "stub this out first," "plan in-place," or "add TODO scaffolding then implement"
• Situations where rationale should survive into final comments

Stub Format

Use this exact marker so cleanup is enforceable:

STUB[<id>]: <single-sentence intent>
IN: <inputs/dependencies>
OUT: <output/observable behavior>
EDGE: <edge cases and failure modes>
DONE: <objective acceptance check>

Rules:

• Keep each field specific and testable; avoid vague stubs like "handle errors"
• Use IDs that are stable within the change (for example auth-01, cache-02)
• Keep one logical change per stub
• Use language-appropriate comment syntax (//, #, --, /* */)

Two-Pass Workflow

1) Recon Pass

• Read affected files and identify exact insertion points
• Confirm constraints (APIs, data contracts, tests, migrations)
• Create a concise task list before editing

2) Stub Pass

• Insert structured STUB[...] blocks directly at intended implementation sites
• Keep control flow visible, but do not write full logic yet
• If useful, add minimal type/function signatures so wiring is obvious

3) Implementation Pass

• Resolve stubs in ID order
• Replace each stub block with working code
• Preserve rationale as durable comments only when still useful
• Run tests/checks after meaningful groups of replacements

4) Cleanup Pass

• Remove unresolved STUB[...] markers unless explicitly requested to keep scaffolding
• Run scripts/check-unresolved-stubs.sh to verify no markers remain
• If a stub must remain intentionally, convert it to a standard project TODO format

Quality Bar

Before finishing:

• No unresolved STUB[...] markers
• Behavior matches each DONE: criterion from the stub pass
• Any retained comments explain why, not what
• Relevant tests updated or added for changed behavior

Output Template

When reporting results, include:

1. Files stubbed in pass 1
2. Stubs replaced in pass 2
3. Final checks run and outcome
4. Any intentional TODOs left behind

Examples

TypeScript example:

// STUB[auth-01]: Validate bearer token and load user session
// IN: Authorization header, user repository
// OUT: AuthenticatedUser or UnauthorizedError
// EDGE: Missing header, malformed token, expired session
// DONE: Protected route returns 401 for invalid token and 200 for valid token

Python example:

# STUB[cache-02]: Add read-through cache for expensive report query
# IN: report_id, db client, cache client
# OUT: report payload with stable schema
# EDGE: cache miss, stale entry, db timeout
# DONE: second request avoids db call and returns equivalent payload