expectations

Expectations: Capturing Learnings

Route each discovery to the artifact that owns its truth. Do not turn one project's architecture, delivery process, or tooling conventions into universal guidance.

Reusable Principle or Local Policy?

• Reusable principle — applies across projects without relying on one repository's names, paths, tools, or release process. Improve the relevant global skill.
• Local policy — depends on this product's domain, architecture, risk posture, workflow, or infrastructure. Record it in repository agent guidance or canonical project documentation.

When in doubt, make the narrower local update. Reuse should be earned by evidence from more than one project, not inferred from one successful implementation.

Documentation Framework

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

Capture a learning if ANY of these are true:

• Would save future developers significant time
• 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

Do not duplicate what the repository already records: current code structure, Git history, or behavior obvious from source and tests.

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

Where Each Learning Goes

If a temporary artifact reveals a lasting constraint, promote the constraint to its owner before deleting the artifact. Git history remains the archive.

Documentation Format

#### 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";

Keep entries scannable: a future reader should grasp context, issue, and solution in under ten seconds.

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
• State explicitly whether a recommendation is a reusable principle or local policy