expectations

Standardize documentation of learnings and working expectations within a codebase.

Updated Nov 8, 2016

Search Tags:#documentation #onboarding #codebase #communication #guidelines #best-practices #learnings

Ready to run

npx skills add https://github.com/jscriptcoder/jscriptcoder.com --skill expectations-jscriptcoder

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: expectations
Source: https://github.com/jscriptcoder/jscriptcoder.com/tree/main/.claude/skills/expectations
Command: npx skills add https://github.com/jscriptcoder/jscriptcoder.com --skill expectations-jscriptcoder

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill provides a disciplined approach to capturing learnings and documenting working expectations, ensuring consistent practices across the codebase.

Core Features & Use Cases

Documentation Framework: Establishes a standard structure for recording decisions, patterns, edge cases, and rationale for code changes.
Knowledge Capture: Guides contributors to document gotchas, design decisions, and trade-offs to improve future maintenance.
Onboarding & Collaboration: Helps new team members understand conventions, reasoning, and review processes.

Quick Start

Summarize the latest code change by capturing decisions, rationale, and potential gotchas.

Frequently Asked Questions about expectations

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

FAQPage Schema

How do I standardize codebase documentation for onboarding and best practices?▼

To standardize codebase documentation, you need a framework that captures learnings and working expectations. This approach uses a structured format with YAML frontmatter to record decisions, rationale, and gotchas for new contributors.

What is the best way to capture code review learnings and design decisions?▼

Capturing code review learnings involves documenting decisions, patterns, edge cases, and rationale for code changes. Using a structured documentation framework ensures this knowledge is recorded consistently to improve future maintenance and team collaboration.

Does this documentation framework require any specific file format?▼

Yes, this documentation framework requires a YAML frontmatter at the beginning of your files. You must include at least the name and description fields in the frontmatter, along with a structured description that features a Quick Start prompt.

How do I document codebase gotchas and edge cases for future maintenance?▼

You document codebase gotchas by applying a standardized knowledge capture process during development. This involves recording design decisions, trade-offs, and rationale within your repository to help future maintainers understand conventions and avoid past mistakes.

Can I use this approach to improve the onboarding process for new developers?▼

Yes, you can use this approach to improve onboarding by providing new team members with standardized documentation. It helps them understand established conventions, review processes, and the reasoning behind specific design decisions across the codebase.

open-gsd

1.0k

multiline-description

Normalize multiline YAML frontmatter descriptions into single-line form, preserving semantic meaning and collapsing newlines for indexing and display.

Official

Basic