poke-holes

Tests understanding of a codebase concept by attacking the user's explanation with file-cited counterexamples.

Updated Dec 18, 2025
One-click install
npx skills add https://github.com/l0lxl0lw/dotfiles --skill poke-holes-l0lxl0lw
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: poke-holes
Source: https://github.com/l0lxl0lw/dotfiles/tree/main/ai/shared/skills/understand/poke-holes
Command: npx skills add https://github.com/l0lxl0lw/dotfiles --skill poke-holes-l0lxl0lw

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Reading an explanation of how a system works creates the illusion of understanding; this Skill exposes gaps by having you explain a concept back in your own words, then attacking every wrong, misreasoned, or underspecified belief with evidence from the actual code. ## Core Features & Use Cases - Grounded explanations: Reads the real implementation first, extracting exact column vocabularies, invariants, and divergences between design docs and code before explaining anything. - Four-verdict assertion grading: Classifies each claim in your explanation as Wrong, Right for the wrong reason, Underspecified, or Right, with every hole backed by a file:line citation and a concrete failing case. - Iterative repair loop: Withholds the correct mechanism for one round so you repair your own model, then loops until a round produces no substantive holes, closing with a diff of your mental model. - Use Case: After reading a billing system's allocation logic, run the skill to explain it back and discover that your belief about when quantity is decremented breaks when a bill is voided. ## Quick Start Ask the AI to poke holes in your understanding of a specific concept in this repository, optionally pointing it at the relevant code path.

Frequently Asked Questions about poke-holes

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

FAQPage Schema
How do I test whether I really understand a codebase concept?

Explain the concept back in your own words without re-reading the code, then have each assertion graded against the actual implementation. This skill decomposes your explanation into discrete claims and attacks wrong or misreasoned ones with file-cited counterexamples.

How to verify my mental model of a system matches the code?

The skill reads the real implementation first, extracting invariants, column vocabularies, and design-doc divergences, then compares your explanation against that ground truth. Every hole it raises includes a file:line citation and a concrete case where your belief produces a wrong outcome.

What makes this different from just reading documentation?

Reading produces passive recognition, while generating an explanation exposes what you actually retained. The skill specifically hunts beliefs that are right for the wrong reason, which survive testing and code review but fail when conditions change.

When does the poke-holes session end?

The loop ends when a revision round produces no Wrong and no Right-for-the-wrong-reason verdicts, with at most cosmetic underspecification. It closes with a short diff showing what you believed at the start versus what you believe now.

What happens if my explanation is already correct?

The skill says so directly, names the two or three non-obvious points you got right, and stops. It never manufactures criticism, since invented holes would destroy trust in the real ones.