home / skills / citypaul / .dotfiles / expectations

expectations skill

safe

This skill guides disciplined development using test-driven code, clear documentation, and thoughtful refactoring, enhancing collaboration and maintainability.

npx playbooks add skill citypaul/.dotfiles --skill expectations

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.7 KB

---
name: expectations
description: Working expectations and documentation practices. Use when capturing learnings or understanding how to work with this codebase.
---

# Expectations

## When Working with Code

1. **ALWAYS FOLLOW TDD** - No production code without a failing test. Non-negotiable.
2. **Think deeply** before making any edits
3. **Understand the full context** of the code and requirements
4. **Ask clarifying questions** when requirements are ambiguous
5. **Think from first principles** - don't make assumptions
6. **Assess refactoring after every green** - but only refactor if it adds value
7. **Keep project docs current** - Update CLAUDE.md when introducing meaningful changes

## Documentation Framework

**At the end of every significant change, ask: "What do I wish I'd known at the start?"**

Document if ANY of these are true:
- Would save future developers >30 minutes
- Prevents a class of bugs or errors
- Reveals non-obvious behavior or constraints
- Captures architectural rationale or trade-offs
- Documents domain-specific knowledge
- Identifies effective patterns or anti-patterns
- Clarifies tool setup or configuration gotchas

## Types of Learnings to Capture

- **Gotchas**: Unexpected behavior discovered (e.g., "API returns null instead of empty array")
- **Patterns**: Approaches that worked particularly well
- **Anti-patterns**: Approaches that seemed good but caused problems
- **Decisions**: Architectural choices with rationale and trade-offs
- **Edge cases**: Non-obvious scenarios that required special handling
- **Tool knowledge**: Setup, configuration, or usage insights

## Documentation Format

```markdown
#### Gotcha: [Descriptive Title]

**Context**: When this occurs
**Issue**: What goes wrong
**Solution**: How to handle it

// CORRECT - Solution
const example = "correct approach";

// WRONG - What causes the problem
const wrong = "incorrect approach";
```

## Code Change Principles

- **Start with a failing test** - always. No exceptions.
- After making tests pass, always assess refactoring opportunities
- After refactoring, verify all tests and static analysis pass, then commit
- Respect the existing patterns and conventions
- Maintain test coverage for all behavior changes
- Keep changes small and incremental
- Ensure all TypeScript strict mode requirements are met
- Provide rationale for significant design decisions

**If you find yourself writing production code without a failing test, STOP immediately and write the test first.**

## Communication

- Be explicit about trade-offs in different approaches
- Explain the reasoning behind significant design decisions
- Flag any deviations from guidelines with justification
- Suggest improvements that align with these principles
- When unsure, ask for clarification rather than assuming

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

FAQ

What belongs in documentation after a change?

Anything that would save future contributors >30 minutes, prevents common bugs, reveals non-obvious constraints, or records rationale for design choices.

What if I need to ship urgent production code without a test?

Stop and write the failing test first. If truly impossible, document why and prioritize adding the test as soon as possible; flag the deviation with justification.