expectations

Documents codebase learnings, gotchas, and architectural decisions using a structured format.

Updated May 30, 2026
One-click install
npx skills add https://github.com/chloebrett/snitchos --skill expectations-chloebrett
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: expectations
Source: https://github.com/chloebrett/snitchos/tree/main/.claude/skills/expectations
Command: npx skills add https://github.com/chloebrett/snitchos --skill expectations-chloebrett

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Hard-won knowledge about a codebase—gotchas, architectural rationale, and effective patterns—often gets lost after a feature ships, forcing future developers to rediscover the same pitfalls. This Skill enforces a disciplined practice of capturing and documenting those learnings alongside strict TDD workflow rules. ## Core Features & Use Cases - Learning Capture Framework: Prompts the question "What do I wish I'd known at the start?" after every significant change, with clear criteria for what deserves documentation. - Structured Documentation Format: Provides a consistent template for recording gotchas, patterns, anti-patterns, decisions, and edge cases with context, issue, and solution sections. - TDD Enforcement: Mandates a failing test before any production code, with refactoring assessment after mutation testing confirms test strength. - Use Case: After debugging a subtle API behavior where an endpoint returns null instead of an empty array, use this Skill to record the gotcha in project docs so the next developer avoids the same trap. ## Quick Start Ask the assistant to document this learning or record this gotcha after finishing a significant code change.

Frequently Asked Questions about expectations

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

FAQPage Schema
How do I document code learnings and gotchas effectively?▼

Document a learning when it would save future developers time, prevent a class of bugs, or reveal non-obvious behavior. Use a structured format with context, issue, and solution sections, including correct and incorrect code examples.

What is the best way to enforce TDD in a development workflow?▼

Require a failing test before any production code is written, with no exceptions. After tests pass, assess refactoring opportunities, verify all tests and static analysis pass, then commit.

When should I update project documentation like CLAUDE.md?▼

Update project documentation whenever you introduce meaningful changes, discover non-obvious behavior, or make architectural decisions with trade-offs. The guiding question is what you wish you had known at the start of the work.

What types of learnings are worth recording after a feature?▼

Record gotchas, effective patterns, anti-patterns, architectural decisions with rationale, edge cases requiring special handling, and tool setup or configuration insights. Skip trivial details that are obvious from reading the code.

When should refactoring happen in a TDD workflow?▼

Refactor only after mutation testing confirms test strength and all tests pass. Refactor only when it adds genuine value, keeping changes small and incremental while respecting existing conventions.