skills.rest
citypaul
citypaulCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

expectations

Capture and organize codebase learnings, decisions, and guidelines in Markdown.

710|89|Updated Nov 14, 2021
Search Tags:#documentation#onboarding#TDD#codebase#guidelines#CLAUDE.md#learnings
One-click install
npx skills add https://github.com/citypaul/.dotfiles --skill expectations-citypaul
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: expectations
Source: https://github.com/citypaul/.dotfiles/tree/main/claude/.claude/skills/expectations
Command: npx skills add https://github.com/citypaul/.dotfiles --skill expectations-citypaul

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill provides a structured approach to capturing learnings, decisions, and guidelines within a codebase, enabling teams to retain institutional knowledge and ensure consistent documentation practices.

Core Features & Use Cases

  • Enforces documentation discipline by organizing learnings (Gotchas, Patterns, Anti-patterns, Decisions, Edge cases, Tool knowledge) and aligning with CLAUDE.md guidelines.
  • Supports onboarding and knowledge transfer by preserving rationale and trade-offs for changes, ensuring new contributors can quickly understand decisions.
  • Facilitates post-mortems and future work planning by documenting context, outcomes, and recommended actions.

Quick Start

Review CLAUDE.md and document your first learning item in this Skill, citing a concrete example from your work.

Frequently Asked Questions about expectations

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

FAQPage Schema
How do I structure codebase learnings and decisions for developer onboarding?▼

Structure codebase learnings by documenting Gotchas, Patterns, Anti-patterns, Decisions, and Edge cases within a Markdown body. This preserves institutional knowledge and helps new contributors understand trade-offs quickly.

What is the best way to document post-mortem reviews and feature exploration guidelines?▼

Document post-mortem reviews by capturing context, outcomes, and recommended actions in structured Markdown. This enforces documentation discipline and ensures future work planning aligns with established guidelines.

Does this documentation approach require YAML frontmatter for codebase guidelines?▼

Yes, this documentation approach requires YAML frontmatter containing name and description fields. It ensures codebase guidelines are properly indexed and discoverable alongside the comprehensive Markdown body.

How do I align captured learnings with CLAUDE.md guidelines?▼

Align captured learnings with CLAUDE.md guidelines by reviewing the file and documenting concrete examples from your work. This ensures consistency between your documented decisions and existing project standards.

Can I use structured Markdown to enforce TDD documentation discipline in my workflow?▼

Yes, you can use structured Markdown to enforce TDD documentation discipline by organizing tool knowledge and patterns. This improves consistency across developer workflows and retains rationale for codebase changes.

Related Skills

Explore More Software Engineering Skills→
mcj-codermcj-coder
1

greenfield-baseline

Automate project scaffolding with quality gates, CI/CD, and repository structure.

Community
Advanced
him55710-sudohim55710-sudo

learn

Consolidate gstack session learnings into a searchable knowledge base.

Community
Advanced
jinwoonghongjinwoonghong

moai

Orchestrate a full software development lifecycle pipeline from planning to deployment.

Community
Advanced
alexanderopalexanderop
15

adding-notes

Convert resource URLs into structured Markdown notes with frontmatter and wiki-links.

Community
Basic