Refine agent onboarding and generic handoff guidance

AGENTS.md

@@ -4,32 +4,34 @@ Repository-wide instructions for any autonomous or semi-autonomous coding agent.
 
 ## Purpose
 
-This repository is intended to be reusable across many projects. Keep changes and documentation generic unless you are actively working inside a specific downstream repo that requires project-specific customization.
+This repository is designed to be reused across many downstream projects. Keep behavior, docs, and naming generic by default unless you are actively working inside a specific downstream repo that requires explicit customization.
 
-## Startup checklist (every run)
+## Startup checklist (run every session)
 
 1. Read this file (`AGENTS.md`).
-2. Read `CLAUDE.md` for operating conventions.
-3. Read `CONTRIBUTING.md` for commit/PR quality expectations.
-4. Check `KNOWN_ISSUES.md` before making changes.
-5. If present, check `docs/agent-handoffs/` for recent agent learnings.
+2. Read `CLAUDE.md` for execution conventions.
+3. Read `CONTRIBUTING.md` for commit/PR expectations.
+4. Check `KNOWN_ISSUES.md` for active blockers or workarounds.
+5. Review `docs/agent-handoffs/README.md` and recent notes in:
+   - `docs/agent-handoffs/learnings/`
+   - `docs/agent-handoffs/incidents/`
 
 ## Generic-first policy
 
 - Do not hardcode organization, product, customer, or brand-specific details.
 - Do not assume a single deployment environment unless explicitly configured.
 - Prefer neutral names such as `project`, `service`, `integration`, `consumer`, `provider`.
-- Add project-specific notes only when working in that project's repo and label them clearly.
+- Add project-specific notes only when working in that project’s own repository, and label them clearly.
 
 ## Agent learning + handoff protocol
 
-Agents are expected to leave concise, reusable notes for later agents.
+Agents are expected to leave concise, reusable notes so future agents do not need to rediscover the same context.
 
-### Where to write
+### Which file should be updated?
 
-- `docs/agent-handoffs/README.md` for folder usage.
-- `docs/agent-handoffs/learnings/` for new practical learnings.
-- `docs/agent-handoffs/incidents/` for issue/incident writeups and mitigations.
+- Update `KNOWN_ISSUES.md` when an issue is active/reproducible and others may hit it.
+- Add a file in `docs/agent-handoffs/learnings/` for reusable successful patterns.
+- Add a file in `docs/agent-handoffs/incidents/` for failures, root cause, and mitigations.
 
 ### Naming convention
 
@@ -37,11 +39,11 @@ Use generic, descriptive filenames:
 
 - `YYYY-MM-DD-short-topic.md` (example: `2026-02-14-lock-timeout-tuning.md`)
 
-Avoid brand, team, or person-specific prefixes in filenames.
+Avoid product, team, or person-specific prefixes.
 
 ### Required note structure
 
-Each note should contain:
+Each learning/incident note should include:
 
 - Context
 - Observation
@@ -49,14 +51,22 @@ Each note should contain:
 - Validation performed
 - Recommendation for next agents
 
-Keep each note short and actionable.
+Keep each note short, actionable, and safe to share (no secrets).
+
+### When to write a note
+
+Write or update a handoff note when you discover:
+
+- A non-obvious fix or command sequence that works reliably.
+- A recurring failure mode and how to prevent it.
+- A validation step that catches common mistakes early.
 
 ## Safety and quality baseline
 
-- Make smallest safe change first.
+- Make the smallest safe change first.
 - Prefer explicit commands over assumptions.
-- Validate with available tests/checks.
-- If blocked by environment limits, document the blocker and fallback.
+- Validate with relevant tests/checks.
+- If blocked by environment limits, record the blocker and fallback.
 
 ## Priority order
 

CLAUDE.md

@@ -10,33 +10,43 @@ Applies to all agent tasks unless superseded by direct runtime instructions.
 
 - Keep output and changes generic by default.
 - Prefer deterministic, auditable steps.
-- Record decisions so future agents can continue with minimal rediscovery.
+- Record useful decisions so future agents can continue with minimal rediscovery.
+
+## Execution flow (recommended)
+
+1. Read policy files listed in `AGENTS.md` startup checklist.
+2. Review current known issues and recent handoff notes.
+3. Implement the smallest safe change.
+4. Validate with relevant checks/tests.
+5. Update shared docs (`KNOWN_ISSUES.md` and/or handoff notes) when new reusable knowledge appears.
 
 ## Handoff documentation workflow
 
 When you learn something that can help future agents:
 
-1. Check for existing related notes in `docs/agent-handoffs/learnings/` and `docs/agent-handoffs/incidents/`.
-2. If the learning is new, add a small markdown note using the naming standard in `AGENTS.md`.
-3. Link related issue patterns in `KNOWN_ISSUES.md` when applicable.
+1. Check for related notes in:
+   - `docs/agent-handoffs/learnings/`
+   - `docs/agent-handoffs/incidents/`
+2. If the insight is new, add a short markdown note using the naming standard from `AGENTS.md`.
+3. If the issue is still active/reproducible, add or update the corresponding entry in `KNOWN_ISSUES.md`.
 4. Keep note content sanitized and reusable (no secrets, no user-identifying details).
 
 ## What belongs where
 
-- `KNOWN_ISSUES.md`: currently active/reproducible issues and known workarounds.
+- `KNOWN_ISSUES.md`: active/reproducible issues, impact, workaround, and current status.
 - `docs/agent-handoffs/learnings/`: durable implementation insights and successful patterns.
-- `docs/agent-handoffs/incidents/`: failure reports, root-cause notes, and prevention guidance.
-- `CONTRIBUTING.md`: process standards for proposing and reviewing changes.
+- `docs/agent-handoffs/incidents/`: failure writeups, root causes, and prevention guidance.
+- `CONTRIBUTING.md`: standards for proposing, validating, and reviewing changes.
 
-## Style for agent notes
+## Style for handoff notes
 
 - Prefer bullets over long prose.
 - Include exact commands where useful.
 - State confidence and remaining uncertainty.
-- End with a “Next agent should …” line.
+- End with: `Recommendation for next agents:`
 
 ## Anti-patterns
 
-- Avoid repo-local jargon in shared templates.
-- Avoid stale TODO dumps without context or owner.
-- Avoid project/brand-specific terms unless explicitly required by the active repo.
+- Avoid repo-local jargon in reusable templates.
+- Avoid stale TODO dumps without context.
+- Avoid project/brand-specific terms unless explicitly required by the active downstream repo.

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# CONTRIBUTING
+# CONTRIBUTING.md
 
 Guidelines for humans and agents proposing changes.
 
@@ -6,14 +6,15 @@ Guidelines for humans and agents proposing changes.
 
 - Keep changes focused and minimal.
 - Explain why a change is needed, not only what changed.
-- Preserve generic behavior unless implementing explicit repo-specific requirements.
+- Preserve generic behavior unless implementing explicit downstream repo requirements.
 
 ## Before opening a PR
 
-1. Confirm instructions in `AGENTS.md` and `CLAUDE.md` were followed.
-2. Run relevant checks/tests.
-3. Update docs affected by behavior changes.
-4. If you discovered reusable information, add/update a note under `docs/agent-handoffs/`.
+1. Confirm `AGENTS.md` and `CLAUDE.md` were followed.
+2. Run relevant checks/tests for the scope of change.
+3. Update docs affected by behavior or workflow changes.
+4. If you discovered reusable information, add/update a note in `docs/agent-handoffs/`.
+5. If an issue remains active, update `KNOWN_ISSUES.md`.
 
 ## Commit guidance
 
@@ -37,4 +38,4 @@ If no tests were run, state why.
 When changing workflows:
 
 - Update `KNOWN_ISSUES.md` for new known limitations/workarounds.
-- Add a learning note if the change uncovered a reusable pattern.
+- Add a learning or incident note if the change uncovered reusable guidance.

KNOWN_ISSUES.md

@@ -1,4 +1,4 @@
-# KNOWN ISSUES
+# KNOWN_ISSUES.md
 
 Track active, reproducible issues in a generic format.
 
@@ -6,7 +6,7 @@ Track active, reproducible issues in a generic format.
 
 - Keep entries short and factual.
 - Remove resolved issues quickly.
-- Link to handoff/incident notes for deep details.
+- Link to handoff/incident notes for deeper context.
 
 ## Entry template
 

docs/agent-handoffs/README.md

@@ -1,11 +1,11 @@
 # Agent Handoffs
 
-This folder stores reusable learnings that help future agents work faster and safer.
+This folder stores reusable knowledge so future agents can work faster and safer.
 
 ## Folders
 
-- `learnings/`: patterns that worked and can be reused.
-- `incidents/`: failures, root causes, and prevention notes.
+- `learnings/`: successful patterns and repeatable implementation guidance.
+- `incidents/`: failures, root causes, and mitigation/prevention notes.
 
 ## Filename format
 
@@ -13,7 +13,24 @@ Use: `YYYY-MM-DD-short-topic.md`
 
 Examples:
 
-- `2026-02-14-command-ordering.md`
+- `2026-02-14-validation-before-summary.md`
 - `2026-02-14-lock-timeout-regression.md`
 
 Keep names generic and descriptive.
+
+## Required note structure
+
+Every note should include:
+
+- Context
+- Observation
+- Action taken
+- Validation performed
+- Recommendation for next agents
+
+## Writing guidelines
+
+- Keep entries short and actionable.
+- Include exact commands when helpful.
+- Avoid secrets or user-identifying data.
+- Prefer generic language unless you are in a specific downstream project repository.

docs/agent-handoffs/incidents/2026-02-14-missing-baseline-context.md

@@ -1,7 +1,7 @@
-# Example Incident: Missing Baseline Context
+# Missing Baseline Context
 
-- **Context:** Agent started editing without reviewing policy files first.
-- **Observation:** Resulting patch required rework to match repo standards.
-- **Action taken:** Re-read policy docs, reverted conflicting edits, reapplied changes correctly.
+- **Context:** Agent started editing without reviewing baseline policy files first.
+- **Observation:** Resulting patch required rework to match repository standards.
+- **Action taken:** Re-read policy docs, reverted conflicting edits, and reapplied changes correctly.
 - **Validation performed:** Compared final output to policy docs and reran checks.
 - **Recommendation for next agents:** Read `AGENTS.md` and `CLAUDE.md` first on every run to avoid avoidable churn.

docs/agent-handoffs/learnings/2026-02-14-validation-before-summary.md

@@ -1,4 +1,4 @@
-# Example Learning: Validation Before Summary
+# Validation Before Summary
 
 - **Context:** Multi-file documentation update.
 - **Observation:** Running quick checks before writing summaries catches avoidable mistakes.