lesson

Lesson Learned

Document the correction the user just gave as a reusable lesson in .aidocs/lessons/: $ARGUMENTS

Steps

0. Read language configuration from .aidocs/config.yaml (or .aidocs/config.yml):

   ! cat .aidocs/config.yaml 2>/dev/null || cat .aidocs/config.yml 2>/dev/null || echo "language: en"

   Extract the language field (default: en if neither file exists or the field is absent). All content written to .aidocs/ must be in this language.

1. Review existing lessons to avoid duplicates and check for related lessons to update instead:

   ! ls .aidocs/lessons/ 2>/dev/null || echo "No lessons yet"

2. Identify the pattern: extract the general, reusable principle from the specific correction. Focus on why the mistake happened and what rule prevents it — not the specific instance.

3. Determine the filename: use today's date and a kebab-case slug that describes the pattern.

   • Format: YYYYMMDD-<pattern-slug>.md
   • Example: 20260403-no-unit-tests-per-class.md

4. Write the lesson in .aidocs/lessons/ using the template below. Every section is mandatory — do not skip any.

5. Present the lesson to the user for review before finishing.

Lesson Template

# <Title: the pattern or rule, stated as a positive principle>

- **Date**: YYYY-MM-DD
- **Status**: Active | Superseded by [Lesson YYYYMMDD](./YYYYMMDD-slug.md)

## Rule

State the rule clearly and concisely in one or two sentences. Use imperative voice: "Do not...", "Always...", "Prefer...".

## Context

Describe in which situations this rule applies. What kind of task, file type, architecture layer, or workflow triggers this pattern? Be specific enough to be actionable but general enough to cover future cases.

## Why

Explain the reasoning behind the rule. What goes wrong when it is violated? What value does following it preserve (consistency, architecture, readability, testability, etc.)?

## Examples

### Wrong

// Concrete, minimal example showing the mistake

### Right

// Concrete, minimal example showing the correct approach

## Related Lessons

- List links to related lessons if any, or write "None".

Guidelines

• Abstract the pattern: a lesson must apply to future similar situations, not just replay the specific mistake. Ask: "Would this lesson prevent the same error in a different file or context?"
• Include both examples: the wrong and right examples are mandatory — they make the rule concrete and unambiguous.
• Examples should be minimal: show only enough code or text to illustrate the contrast. No full file dumps.
• If an existing lesson is close: update it instead of creating a new file. Add to its examples or refine its rule.
• If this supersedes a previous lesson: update the old lesson's status to Superseded by [Lesson YYYYMMDD](./YYYYMMDD-slug.md).
• Do not document one-off quirks: if the correction was highly specific to a single case and unlikely to recur, ask the user whether it is worth generalizing before writing the lesson.