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.

Quality

69%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/codebase-assumption-capture/SKILL.md

Quality

Content

60%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is highly actionable with a precise YAML schema and worked examples, but it is significantly over-long and repetitive, and it makes no use of progressive disclosure despite being large enough to clearly warrant splitting example/schema material into reference files.

Suggestions

Move the six full Example Scenarios and the YAML schema into a references/ file (e.g. references/examples.md) and keep only one representative example plus a schema summary in SKILL.md, with a clear one-level-deep link.

Cut the redundant sections (Purpose, Benefits, Future Use, Important Guidelines largely restate the trigger checklist and workflow) to roughly halve the body length.

Collapse the four chat-script Failure Examples into a single short "when this should have triggered" note, since the trigger checklist already enumerates the same cases.

Dimension	Reasoning	Score
Conciseness	The ~500-line body is noticeably verbose and repetitive: the four chat-script Failure Examples, the six full YAML Example Scenarios, the Purpose section, Benefits, Important Guidelines, Future Use, and Integration sections all restate the same concept of "wrong assumptions reveal documentation gaps," and the YAML schema appears three times.	2 / 5
Actionability	Provides fully concrete, copy-paste-ready guidance: a complete YAML schema, six fully worked example entries, an exact file location (.claude/assumption-corrections.yaml), and explicit format rules for every field including enumerated categories and impact levels.	5 / 5
Workflow Clarity	A clear four-step sequence (Realize -> Silent Logging -> File Management -> User Review) is present and well-ordered; the destructive/batch cap does not apply because the operation is a low-risk silent log append, but explicit validation (e.g. confirming the appended YAML is well-formed) is absent.	4 / 5
Progressive Disclosure	No bundle files exist and everything is inlined into one monolithic document; the six full YAML examples and the schema clearly belong in a separate reference file, and there are no one-level-deep references to split out this detail.	2 / 5
	Total	13 / 20 Passed

Description

78%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description that clearly states what it does and when to trigger it, with concrete examples and an explicit distinction from related skills. The main weakness is second-person voice ("you made"), which lowers the specificity score per the voice guideline.

Suggestions

Rewrite in third person to avoid the second-person voice penalty, e.g. "Captures wrong assumptions made about the codebase" instead of "Capture wrong assumptions you made".

Consider adding natural user-side phrasing (e.g. mentions of "wrong assumption", "turned out to be", "I thought it was X but it's Y") alongside the AI-self-trigger framing.

Dimension	Reasoning	Score
Specificity	Names several concrete actions ("Capture wrong assumptions", "Log silently to .claude/assumption-corrections.yaml", "identify CLAUDE.md documentation gaps") which would warrant a 4, but reduced by one for second-person voice ("assumptions you made").	3 / 5
Completeness	Explicitly answers both what (capture/log wrong assumptions to identify CLAUDE.md gaps) and when ("TRIGGER when reality differs from expectation" with concrete examples), satisfying the explicit-trigger-guidance requirement.	5 / 5
Trigger Term Quality	Good keyword coverage with natural trigger phrases and concrete examples ("assumed Jest but it's Vitest", "assumed REST but it's GraphQL", "assumed AbstractUseCase exists but found AbstractMemberUseCase"), though framed for AI self-triggering rather than phrased as a user would say them.	4 / 5
Distinctiveness Conflict Risk	Has a clear niche (logging wrong codebase assumptions to a specific file) and explicitly distinguishes itself from sibling skills ("Key distinction - assumptions are corrected by reality, decisions are choices between valid options"), with only minor overlap risk against the related capture skills it references.	4 / 5
	Total	16 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (508 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: cteyton/packmind
Path: .claude/skills/codebase-assumption-capture/SKILL.md
Commit: e198635

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.