expectations

Capture learnings, gotchas, and architectural decisions into the correct project documentation files.

Updated May 18, 2024
One-click install
npx skills add https://github.com/joshhornby/dotfiles --skill expectations-joshhornby
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: expectations
Source: https://github.com/joshhornby/dotfiles/tree/main/.claude/skills/expectations
Command: npx skills add https://github.com/joshhornby/dotfiles --skill expectations-joshhornby

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? After finishing significant work, valuable insights like gotchas, patterns, and architectural rationale are easily lost. This Skill provides a decision framework for determining what is worth documenting, where each type of knowledge belongs, and how to format it so future developers and AI sessions benefit. ## Core Features & Use Cases - Documentation Triage: Decides whether a learning belongs in the project CLAUDE.md, an ADR in docs/adr/, an active plan file, auto-memory, or the README based on its type and audience. - Learning Classification: Distinguishes gotchas, patterns, anti-patterns, architectural decisions, edge cases, and tool knowledge, with explicit criteria for what is worth recording versus what the repo already shows. - Standard Format: Provides a scannable Context/Issue/Solution template with correct and wrong code examples so entries can be grasped in under ten seconds. - Use Case: After debugging a subtle API behaviour where an endpoint returns null instead of an empty array, use this Skill to record the gotcha in the project CLAUDE.md with context, issue, and solution before the session ends. ## Quick Start Ask the assistant to document this learning or record this gotcha from the work just completed, and it will place the entry in the right documentation file.

Frequently Asked Questions about expectations

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

FAQPage Schema
How do I document learnings and gotchas in a software project?

Identify what you wish you had known at the start, then record it using a Context, Issue, Solution format with correct and wrong code examples. Place repo-specific gotchas in the project CLAUDE.md so they load every session.

Where should architectural decisions be documented?

Architectural decisions with rationale and rejected alternatives belong in an ADR under docs/adr/ or the project's convention. Decisions need permanence and context beyond what a config file like CLAUDE.md provides.

What is the difference between CLAUDE.md and an ADR for documentation?

CLAUDE.md holds gotchas, patterns, and tool knowledge that affect how work happens in the repo and is loaded every session. ADRs capture one-time architectural choices with trade-offs and rejected alternatives for long-term reference.

What should not be documented in project docs?

Do not document anything the repo already records, such as code structure, git history, or anything derivable by reading the code. Documentation should cover non-obvious behaviour, rationale, and time-saving insights only.

When should I capture learnings during a feature?

Capture in-flight discoveries like blockers and scope changes in the active plan file as they happen. At the end of a feature, sweep the whole session for documentation-worthy insights rather than relying on recall.