Refactor lessons to use shared prompt components and link to standalone pages

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ofriw

website/docs/practical-techniques/lesson-10-debugging.md

@@ -4,6 +4,8 @@ sidebar_label: 'Lesson 10: Debugging'
 title: 'Lesson 10: Debugging with AI Agents'
 ---
 
+import EvidenceBasedDebug from '@site/shared-prompts/\_evidence-based-debug.mdx';
+
 Debugging with AI agents isn't about describing symptoms and hoping for solutions. It's about requiring evidence at every step. The core principle: **never accept a fix without reproducible proof it works**.
 
 ## Always Require Evidence
@@ -14,6 +16,8 @@ The fundamental shift in debugging with AI is moving from "what do you think is
 
 **Production pattern:** Provide reproduction steps, give the agent access to diagnostic tools, and require before/after evidence.
 
+<EvidenceBasedDebug />
+
 ## Code Inspection: Understanding Before Fixing
 
 Before diving into logs or reproduction, have the agent explain the architecture and execution flow. Use conversational analysis to identify mismatches between your mental model and actual system behavior. Ask the agent to trace request paths, explain data flow, and identify potential failure points based on code structure.

website/docs/practical-techniques/lesson-6-project-onboarding.md

@@ -6,6 +6,7 @@ title: 'Lesson 6: Project Onboarding'
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import GenerateAgentsMD from '@site/shared-prompts/\_generate-agents-md.mdx';
 
 When you join a new project, the first week is brutal. You're swimming in unfamiliar architecture, tech stack decisions, tribal knowledge buried in Slack threads, and that one critical bash script everyone runs but nobody documented.
 
@@ -221,30 +222,14 @@ npm run deploy                       # Deploy to GitHub Pages
 
 **The meta-move: Apply lessons 3-5 to generate context files automatically.** Instead of manually drafting `AGENTS.md` or `CLAUDE.md`, use the four-phase workflow ([Lesson 3](/docs/methodology/lesson-3-high-level-methodology)) to let agents bootstrap their own context. **Research phase:** Use ChunkHound's `code_research()` tool to understand your project's architecture, patterns, and conventions—query for architecture, coding styles, module responsibilities, and testing conventions, etc to build a comprehensive architectural understanding. Use ArguSeek's `research_iteratively()` and `fetch_url()` to retrieve framework documentation, best practices, and security guidelines relevant to your tech stack. **Plan phase:** The agent synthesizes codebase insights (from ChunkHound) and domain knowledge (from ArguSeek) into a structured context file plan. **Execute phase:** Generate the context file using prompt optimization techniques specific to your model. **Validate phase:** Test the generated context with a typical task, iterate based on gaps.
 
-**Concrete example prompt:**
-
-```
-Generate AGENTS.md for this project.
-Use the code research tool to to learn the project architecture, tech stack,
-how auth works, testing conventions, coding style, and deployment process.
-Use ArguSeek to fetch current best practices for the tech stack used and the
-latest security guidelines.
-
-Create a concise file (≤500 lines) with sections:
-- Tech Stack
-- Development Commands (modified for non-interactive execution)
-- Architecture (high-level structure)
-- Coding Conventions and Style
-- Critical Constraints
-- Common Pitfalls (if found).
-
-Do NOT duplicate information already in README or code comments—instead, focus
-exclusively on AI-specific operations: environment variables, non-obvious
-dependencies, and commands requiring modification for agents.
-```
+<GenerateAgentsMD />
 
 This prompt demonstrates grounding ([Lesson 5](/docs/methodology/lesson-5-grounding)): ChunkHound provides codebase-specific context, ArguSeek provides current ecosystem knowledge, and structured Chain-of-Thought ensures the agent follows a methodical path. The result: production-ready context files generated in one iteration, not manually curated over weeks. Add tribal knowledge manually afterward—production incidents, team conventions, non-obvious gotchas that only humans know.
 
+:::tip Reference
+See the complete prompt template with validation guidance and adaptations: [Generate AGENTS.md](/prompts/onboarding/generate-agents-md)
+:::
+
 ---
 
 **Next:** [Lesson 7: Planning & Execution](./lesson-7-planning-execution.md)

website/docs/practical-techniques/lesson-8-tests-as-guardrails.md

@@ -5,6 +5,8 @@ title: 'Lesson 8: Tests as Guardrails'
 ---
 
 import ThreeContextWorkflow from '@site/src/components/VisualElements/ThreeContextWorkflow';
+import EdgeCaseDiscovery from '@site/shared-prompts/\_edge-case-discovery.mdx';
+import TestFailureDiagnosis from '@site/shared-prompts/\_test-failure-diagnosis.mdx';
 
 AI agents can refactor half your codebase in minutes. They'll rename functions, restructure modules, and update dozens of files—all while you grab coffee. This velocity is powerful, but dangerous. Small logic errors compound fast when changes happen at scale.
 
@@ -22,25 +24,13 @@ Before writing tests, use the planning techniques from [Lesson 7](./lesson-7-pla
 
 **Prompt pattern for edge case discovery:**
 
-```
-How does validateUser() work? What edge cases exist in the current implementation?
-What special handling exists for different auth providers?
-Search for related tests and analyze what they cover.
-```
+<EdgeCaseDiscovery />
 
-The agent searches for the function, reads implementation, finds existing tests, and synthesizes findings. This loads concrete constraints into context: OAuth users skip email verification, admin users bypass rate limits, deleted users are rejected.
+The agent searches for the function, reads implementation, finds existing tests, and synthesizes findings from Step 1. This loads concrete constraints into context: OAuth users skip email verification, admin users bypass rate limits, deleted users are rejected. Step 2 analyzes the implementation against your questions and identifies untested paths. You now have a grounded list of edge cases derived from actual code, not generic testing advice.
 
-**Follow up to identify gaps:**
-
-```
-Based on the implementation you found, what edge cases are NOT covered by tests?
-What happens with:
-- Null or undefined inputs
-- Users mid-registration (incomplete profile)
-- Concurrent validation requests
-```
-
-The agent analyzes the implementation against your questions and identifies untested paths. You now have a grounded list of edge cases derived from actual code, not generic testing advice.
+:::tip Reference
+See the complete prompt template with additional examples and adaptations: [Edge Case Discovery](/prompts/testing/edge-case-discovery)
+:::
 
 ### Closed Loop: Evolve Code Alongside Tests
 
@@ -181,25 +171,7 @@ When tests fail, apply the same four-phase workflow from [Lesson 3](../methodolo
 
 This diagnostic prompt applies techniques from [Lesson 4](../methodology/lesson-4-prompting-101.md): [Chain-of-Thought](../methodology/lesson-4-prompting-101.md#chain-of-thought-paving-a-clear-path) sequential steps, [constraints](../methodology/lesson-4-prompting-101.md#constraints-as-guardrails) requiring evidence, and [structured format](../methodology/lesson-4-prompting-101.md#applying-structure-to-prompts). Understanding why each element exists lets you adapt this pattern for other diagnostic tasks.
 
-````markdown title="Diagnostic Prompt for Test Failures"
-```
-$FAILURE_DESCRIPTION
-```
-
-Use the code research to analyze the test failure above.
-
-DIAGNOSE:
-
-1. Examine the test code and its assertions.
-2. Understand and clearly explain the intention and reasoning of the test - what is it testing?
-3. Compare against the implementation code being tested
-4. Identify the root cause of failure
-
-DETERMINE:
-Is this a test that needs updating or a real bug in the implementation?
-
-Provide your conclusion with evidence.
-````
+<TestFailureDiagnosis />
 
 **Why this works:**
 
@@ -212,6 +184,10 @@ Provide your conclusion with evidence.
 
 You can adapt this for performance issues, security vulnerabilities, or deployment failures by changing the diagnostic steps while preserving the structure: sequential CoT → constrained decision → evidence requirement.
 
+:::tip Reference
+See the complete prompt template with detailed usage examples and adaptations: [Test Failure Diagnosis](/prompts/testing/test-failure-diagnosis)
+:::
+
 ## Key Takeaways
 
 - **Tests are documentation agents actually read** - They learn intent, edge cases, and constraints from test names, assertions, and comments. Write tests that explain the "why," not just verify the "what."

website/docs/practical-techniques/lesson-9-reviewing-code.md

@@ -4,6 +4,9 @@ sidebar_label: 'Lesson 9: Reviewing Code'
 title: 'Reviewing Code'
 ---
 
+import DualOptimizedPR from '@site/shared-prompts/\_dual-optimized-pr.mdx';
+import AIAssistedReview from '@site/shared-prompts/\_ai-assisted-review.mdx';
+
 You've completed the implementation. Tests pass. The agent executed your plan successfully. Now comes the critical question: is it actually correct?
 
 This is the **Validate** phase from [Lesson 3's four-phase workflow](../methodology/lesson-3-high-level-methodology.md)—the systematic quality gate before shipping. Code review catches the probabilistic errors that agents inevitably introduce: subtle logic bugs, architectural mismatches, edge cases handled incorrectly, patterns that don't quite fit your codebase.
@@ -60,6 +63,10 @@ DO NOT EDIT ANYTHING - only review.
 
 After implementing code ([Lesson 7](./lesson-7-planning-execution.md)), writing tests ([Lesson 8](./lesson-8-tests-as-guardrails.md)), and making everything pass, this review step catches what the iterative development process left behind—the final quality gate before committing.
 
+:::tip Reference
+See the complete prompt template with iterative review guidance: [Comprehensive Code Review](/prompts/code-review/comprehensive-review)
+:::
+
 ### Iterative Review: Repeat Until Green or Diminishing Returns
 
 Code review is rarely one-pass—first review finds issues, you fix them, re-run tests ([Lesson 8](./lesson-8-tests-as-guardrails.md)) to catch regressions, then review again in a fresh context (not the same conversation where the agent will defend its prior decisions). Continue this cycle: review in fresh context, fix issues, validate with tests, repeat.
@@ -95,34 +102,7 @@ Traditional PR descriptions optimize for one audience or the other—too verbose
 
 This prompt demonstrates multiple techniques from [Lesson 4 (Prompting 101)](../methodology/lesson-4-prompting-101.md), [Lesson 5 (Grounding)](../methodology/lesson-5-grounding.md), and [Lesson 7 (Planning & Execution)](./lesson-7-planning-execution.md):
 
-```markdown
-You are a contributor to {PROJECT_NAME} creating a GitHub pull request for the current branch.
-Using the sub task tool to conserve context, explore the changes in the git history relative to main.
-Summarize and explain them like you would to a fellow co-worker:
-
-- Direct and concise
-- Professional but conversational
-- Assume competence and intelligence
-- Skip obvious explanations
-
-The intent of the changes are:
-{CHANGES_DESC}
-
-Building upon this, draft two markdown files: one for a human reviewer/maintainer of the project
-and another complementary that's optimized for the reviewer's agent. Explain:
-
-- What was done and the reasoning behind it
-- Breaking changes, if any exist
-- What value the changes adds to the project
-
-Constraints:
-
-- The human optimized markdown file should be 1-3 paragraphs max
-- Agent optimized markdown should focus on explaining the changes efficiently
-
-Use ArguSeek, learn how to explain and optimize both for humans and LLMs.
-Use the code research to learn the overall architecture, module responsibilities and coding style.
-```
+<DualOptimizedPR />
 
 ### Mechanisms at Work
 
@@ -138,6 +118,10 @@ This sub-agent capability is unique to Claude Code CLI. Other tools (Codex, GitH
 
 **Evidence requirements ([Lesson 7](./lesson-7-planning-execution.md#require-evidence-to-force-grounding)):** The prompt forces grounding through "explore the changes" and "learn the architecture"—the agent cannot draft accurate descriptions without reading actual commits and code.
 
+:::tip Reference
+See the complete prompt template with workflow integration tips: [Dual-Optimized PR Description](/prompts/pull-requests/dual-optimized-pr)
+:::
+
 ### Reviewing PRs with AI Assistants
 
 When you're on the receiving end of a PR with dual-optimized descriptions, you have structured context for both human understanding and AI-assisted review. This section shows how to leverage both descriptions effectively.
@@ -160,39 +144,11 @@ When you're on the receiving end of a PR with dual-optimized descriptions, you h
 
 When reviewing a PR with dual-optimized descriptions, use this pattern with your AI assistant:
 
-````markdown
-You are {PROJECT_NAME}'s maintainer reviewing {PR_LINK}. Ensure code quality, prevent technical debt, and maintain architectural consistency.
-
-Context from the PR author:
-{PASTE_AI_OPTIMIZED_DESCRIPTION}
-
-# Review Process
-
-1. Use GitHub CLI to read the PR discussions, comments, and related issues
-2. Think step by step, but only keep a minimum draft for each thinking step, with 5 words at most. End the assessment with a separator ####.
-3. Never speculate about code you haven't read - investigate files before commenting
-
-# Critical Checks
-
-Before approving, verify:
+<AIAssistedReview />
 
-- Can existing code be extended instead of creating new?
-- Does this respect module boundaries and responsibilities?
-- Are there similar patterns elsewhere? Search the codebase.
-- Is this introducing duplication?
-
-# Output Format
-
-```markdown
-**Summary**: [One sentence verdict]
-**Strengths**: [2-3 items]
-**Issues**: [By severity: Critical/Major/Minor with file:line refs]
-**Reusability**: [Specific refactoring opportunities]
-**Decision**: [APPROVE/REQUEST CHANGES/REJECT]
-```
-
-Start by executing `gh pr view {PR_LINK} --comments`, follow with the Code Research tool for codebase understanding.
-````
+:::tip Reference
+See the complete prompt template with Chain of Draft explanation: [AI-Assisted PR Review](/prompts/pull-requests/ai-assisted-review)
+:::
 
 :::tip Chain of Draft (CoD): An Efficient Alternative to Chain of Thought