codebase-assumption-capture
Capture wrong assumptions you made about the codebase. TRIGGER when reality differs from expectation (e.g., "assumed Jest but it's Vitest", "assumed AbstractUseCase exists but found AbstractMemberUseCase", "assumed REST but it's GraphQL"). Log silently to .claude/assumption-corrections.yaml to identify CLAUDE.md documentation gaps. Key distinction - assumptions are corrected by reality, decisions are choices between valid options.
npx skills add majiayu000/claude-skill-registry --skill codebase-assumption-capture --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
The skill helps AI agents identify and record incorrect assumptions made about the codebase. When reality differs from expectation, it triggers logging of the correction to .claude/assumption-corrections.yaml. It distinguishes between assumptions and decisions, and focuses on documenting mismatches to improve CLAUDE.md onboarding material.
How it works
- Triggered when an incorrect assumption is discovered during exploration or implementation. The skill logs the correction silently to .claude/assumption-corrections.yaml without user interaction.
- The log entry follows a YAML structure including fields such as timestamp, category, assumption, reality, discovery_point, impact, misleading_signals, documentation_gap, files_explored, and tags. This mirrors examples in the provided guidance.
- The file location for logging is always the repository root at .claude/assumption-corrections.yaml, and entries are appended with the most recent at the end.
- It treats an assumption as what was initially expected and records the actual reality, plus context to identify documentation gaps for CLAUDE.md.
When to use it
- Use when you realize you were wrong about framework/library, architectural pattern, file structure, naming, or other non-obvious aspects.
- Log immediately upon realizing the incorrect assumption, then continue with corrected understanding.
What it can touch
- The logging target is .claude/assumption-corrections.yaml at repository root. The skill does not modify code files beyond documenting the assumption correction.
Caveats
- Logging is described as silent and automatic; it does not prompt the user for confirmation and does not reveal the log to the user during operation.
- The YAML structure requires specific fields as shown in the integration examples; missing fields should be populated only if provided by the skill’s findings.
# Codebase Assumption Capture Skill This skill helps AI agents track assumptions they made about the codebase that turned out to be incorrect. The goal is to identify documentation gaps and create better onboarding context for future AI agent sessions. ## TRIGGER CHECKLIST - Read This First **TRIGGER THIS SKILL IMMEDIATELY WHEN:** ### Pre-Work Assumptions (before you start coding) - [ ] You assumed a framework/library was used but found a different one (e.g., assumed Jest, found Vitest) - [ ] You assumed an architectural pattern but discovered a different one (e.g., assumed MVC, found hexagonal) - [ ] You assumed a file/folder was the entry point but it wasn't - [ ] You assumed a naming convention but found the opposite - [ ] You found something non-obvious that CLAUDE.md should mention ### During Implementation (when starting to code) - [ ] You started implementing with a wrong assumption and had to change approach - [ ] You assumed you'd find a pattern/template to follow but it doesn't exist - [ ] You assumed certain helpers/utils existed but they don't (or they work differently) - [ ] You assumed the testing setup works a certain way but it doesn't - [ ] You thought a base class
- TRIGGER CHECKLIST - Read This First
- Pre-Work Assumptions (before you start coding)
- During Implementation (when starting to code)
- Post-Implementation Realizations
- Failure Examples - When This Skill SHOULD Have Been Triggered
- Failure Example 1: During Exploration (Classic)
- Failure Example 2: During Implementation (Common!)
- Failure Example 3: Build/Test Failure Reveals Assumption
- Failure Example 4: Helper/Util Assumption
- Purpose
- When to Use This Skill
- When NOT to Use
- Workflow
- Step 1: Realize Assumption Was Wrong
What does the codebase-assumption-capture skill do?
Capture wrong assumptions you made about the codebase. TRIGGER when reality differs from expectation (e.g., "assumed Jest but it's Vitest", "assumed AbstractUseCase exists but found AbstractMemberUseCase", "assumed REST but it's GraphQL"). Log silently to .claude/assumption-corrections.yaml to identify CLAUDE.md documentation gaps. Key distinction - assumptions are corrected by reality, decisions are choices between valid options.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill codebase-assumption-capture --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.