expectations_skill

Overview

This skill codifies working expectations and documentation practices for a dotfiles codebase. It enforces a strict TDD-first workflow and a habit of capturing learnings after meaningful changes. The guidance focuses on preventing recurring problems by documenting gotchas, patterns, decisions, and setup nuances. Use it to keep the repo maintainable, predictable, and easy for new contributors to pick up.

How this skill works

The skill inspects change workflows and prompts contributors to start with a failing test before writing production code. After changes are made, it requires assessing refactors, verifying tests and static analysis, and updating documentation when a change would save time or prevent bugs. It provides a concise documentation format for capturing context, issue, and solution so learnings are searchable and actionable.

When to use it

• When introducing any meaningful change to the codebase
• When you discover unexpected behavior or edge cases
• When making architectural or design decisions with trade-offs
• When onboarding new contributors or sharing setup details
• When assessing whether a refactor adds clear value

Best practices

• Always start with a failing test; do not write production code first
• Think from first principles and understand full context before editing
• Keep changes small and incremental and maintain test coverage
• Document anything that would save future developers >30 minutes or prevent a class of bugs
• Be explicit about trade-offs and flag deviations from guidelines with justification

Example use cases

• Add a new shell utility: write failing tests, implement, refactor, then document setup gotchas
• Fix a flaky script: capture the root cause as a Gotcha with reproduction steps
• Choose between two config management approaches: record rationale and trade-offs as a Decision
• Encounter surprising CLI behavior: document the edge case and correct usage example
• Onboard a teammate: share Patterns and Tool knowledge to shorten ramp time