expectations
Working expectations and documentation practices. Use when capturing learnings or understanding how to work with this codebase.
Best use case
expectations is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Working expectations and documentation practices. Use when capturing learnings or understanding how to work with this codebase.
Teams using expectations should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/expectations/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How expectations Compares
| Feature / Agent | expectations | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Working expectations and documentation practices. Use when capturing learnings or understanding how to work with this codebase.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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
Related Skills
worklog
Update worklog files by moving tasks between todo/doing/done states. Use when recording task progress, starting new work, or marking tasks complete. Requires explicit arguments: worklog [done|doing|todo] [description].
template-proposal-review
Review proposal files in localdocs/localdocs/proposals/ and decide whether to apply them to the upstream python-project-template repository. Use when evaluating proposals generated by template-upstream, deciding which ones to accept or reject, and applying accepted ones to the template repo. Triggers on: "proposal 검토", "제안 검토", "template에 반영할지", "proposals 리뷰", "upstream 반영 결정".
template-downstream
Update .claude/, .mcp.json, and .pre-commit-config.yaml from the upstream python-project-template repository into the current project. Only files that exist upstream are updated — project-only files are never deleted. Use when pulling latest tooling, rules, hooks, or skills from the canonical template into this project. Triggers on: "템플릿 최신화", "template sync", "upstream 반영", "template 업데이트".
template-broadcast
Apply template-downstream to all registered downstream projects in bulk, one project at a time. Use when you want to push the latest .claude/, .mcp.json, or .pre-commit-config.yaml to every project at once. Triggers on: "일괄 배포", "전체 프로젝트에 내려보내기", "모든 프로젝트 업데이트", "broadcast template", "bulk sync".
tdd
Test-Driven Development workflow. Use for ALL code changes - features, bug fixes, refactoring. TDD is non-negotiable.
sparks-create
Apply the 13 thinking tools from "Sparks of Genius" (생각의 탄생) to reframe any problem through creative, cross-disciplinary lenses. Use when conventional analysis falls short, when you need a fresh creative angle, or when the problem spans multiple domains.
skill-creator
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
rethink-unblock
Break out of a stuck approach by reframing a technical problem through structured thinking frameworks. Use when blocked, going in circles, or when a fresh perspective is needed on architecture, design, or debugging.
refactoring
Refactoring assessment and patterns. Use after tests pass (GREEN phase) to assess improvement opportunities.
python-mcp-expert
Expert assistant for developing Model Context Protocol (MCP) servers in Python. Use when creating, debugging, or optimizing MCP servers with FastMCP, tools, resources, and prompts.
python-conventions
Python coding conventions and guidelines including PEP 8, type hints, docstrings, and testing standards. Automatically applied when working with Python files.
prd
Generate high-quality Product Requirements Documents (PRDs) for software systems and AI-powered features. Includes executive summaries, user stories, technical specifications, and risk analysis.