extract-learnings

Extract learnings about team style, preferences, and engineering practices from PR review comments, then save them to the project's general_coding_instructions.md file.

Target File: general_coding_instructions.md

All learnings extracted from PR feedback should be saved to general_coding_instructions.md. This file contains team-wide coding conventions, style preferences, and best practices.

File location:

• In azure-messaging-ai-context repo: .github/general_coding_instructions.md
• In higher-level repos: deps/azure-messaging-ai-context/.github/general_coding_instructions.md

Before Adding Learnings

1. Read the current file: Read .github/general_coding_instructions.md to understand its structure and existing content.
2. Check for duplicates: Ensure the learning is not already documented. If it exists, skip it.
3. Find the right section: Match the learning to an existing section (e.g., Code Style, Error Handling, Testing) or add a new section if needed.
4. Add the learning: Add the learning to the appropriate section.

Workflow

Step 1: Fetch PR Comments

Fetch all comment threads from the PR:

• Focus on reviewer comments that indicate style preferences, corrections, or best practices
• Look for patterns in feedback across multiple comments

For Azure DevOps PRs

URL pattern: https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/{id}

1. Use mcp__azure-devops__repo_list_repos_by_project to get repository ID
2. Use mcp__azure-devops__repo_list_pull_request_threads to fetch all threads
3. For each thread, use mcp__azure-devops__repo_list_pull_request_thread_comments if needed

For GitHub PRs

URL pattern: https://github.com/{owner}/{repo}/pull/{number}

Use the pre-built parsing script that fetches and filters comments directly.

IMPORTANT: Use -ShowResolved YES to include ALL comments (resolved and unresolved) for extracting learnings:

pwsh -File .github/scripts/parse_github_pr_comments.ps1 -prUrl "https://github.com/owner/repo/pull/123" -outputDir "cmake" -ShowResolved YES

Then read the output: Read cmake/extract-learnings/github_pr_comments_parsed.txt

The script automatically:

• Fetches comments via gh api (requires GitHub CLI authenticated)
• With -ShowResolved YES: Shows ALL comments for learning extraction
• With -ShowResolved NO: Only shows active/unresolved comments
• Groups comments by file for easier reading
• Shows active comment count vs resolved count
• Writes output to cmake/extract-learnings/github_pr_comments_parsed.txt for easy access

Step 1b: Handle Large Azure DevOps API Responses

When Azure DevOps PR threads are too large (>25K tokens), the API response cannot be read directly:

1. Save response to file: Let the API response save to tool-results folder (this happens automatically when response is too large)
2. Use the pre-built parsing script at .github/scripts/parse_pr_threads.ps1
3. Run with -ShowResolved YES to include ALL threads for learning extraction:

   pwsh -File .github/scripts/parse_pr_threads.ps1 -jsonFile "<path-to-tool-results>" -outputDir "cmake" -ShowResolved YES

4. Read the output: Read cmake/pr_threads_parsed.txt

The script automatically filters out:

• Bot comments (MerlinBot, Azure Pipelines)
• PR-level comments without file context
• With -ShowResolved YES: Includes closed/resolved threads for learning extraction
• With -ShowResolved NO: Only shows active threads

Output is written to cmake/pr_threads_parsed.txt for easy access.

Filtering PR Comments

Include:

• Comments with threadContext (file-specific feedback)
• All statuses (closed threads can still provide value)
• Human reviewers (team members)

Exclude:

• Bot comments (MerlinBot, Azure Pipelines, etc.)
• PR-level comments without file context
• System-generated threads (build status, etc.)

Step 2: Categorize Learnings

Match learnings to existing sections in general_coding_instructions.md:

If a learning doesn't fit an existing section, propose a new section.

Step 3: Identify Specific Patterns

Look for these types of learnings in feedback:

1. Direct Corrections:
   • "Use X instead of Y"
   • "This should be..."
   • "Wrong pattern, correct is..."
2. Style Preferences:
   • "We prefer..."
   • "Team convention is..."
   • "Always/Never do..."
3. Implicit Patterns:
   • Repeated similar corrections across multiple comments
   • Consistent feedback about specific constructs
   • Comments indicating codebase-wide patterns (e.g., "do this everywhere", "same issue")
4. Best Practices:
   • Performance recommendations
   • Safety/security patterns
   • Thread-safety requirements

Learning Prioritization

High Priority (always capture):

• Comments indicating team-wide conventions (e.g., "do this everywhere", "same issue")
• Thread-safety/deadlock patterns
• Memory leak prevention patterns
• Patterns repeated by multiple reviewers

Medium Priority (capture if generalizable):

• Style preferences with clear reasoning
• Performance recommendations
• Test patterns

Step 4: Formulate Learning Statements

Convert raw feedback into actionable learning statements:

From PR Comment:

"const can't size arrays in MSVC, use #define"

Learning Statement:

#### Array Sizes: Use `#define`, Not `const`
MSVC doesn't support VLAs. Use `#define` macros for array sizes:
```c
// WRONG
const uint32_t size = 3;
TYPE items[size];  // Compiler error!

// CORRECT
#define SIZE 3
TYPE items[SIZE];

### Step 5: Check for Duplicates

Before adding learnings, check if they already exist in `.github/general_coding_instructions.md`:

1. **Read the guidelines file**:
   - Read `.github/general_coding_instructions.md`
   - Understand its structure and existing sections
   - Check if the learning is already documented

2. **Duplicate Detection Rules**:
   - If a learning is already documented, **skip it**
   - Only add learnings that are:
     - Team-specific preferences not already in the file
     - New conventions established through PR feedback
     - Corrections to or clarifications of existing patterns

### Step 6: Present Proposed Changes

Before modifying any files, present a **numbered list** of proposed learnings so the user can select which to keep:

1. **Group learnings by target section** in general_coding_instructions.md
2. **Present each learning as a numbered item**:

1. [Function Naming] Use snake_case for all internal helpers (Source: PR comment #123)
2. [Error Handling] Always log all parameters on validation failure (Source: PR comment #456)
3. [Memory Management] Use malloc_2 for array allocations (Source: PR comment #789)

3. **Ask user to respond with**:
- Specific numbers to keep (e.g., "1, 3")
- "keep all" to apply all proposed changes
4. **Only apply the selected learnings**

### Step 7: Update general_coding_instructions.md

After approval:
1. **Read the current file**: Read `.github/general_coding_instructions.md` to get the current content
2. **Find the target section**: Locate the appropriate section for each learning
3. **Add the learning**: Use the `Edit` tool to add the learning to the appropriate section
4. **Create new sections if needed**: If no existing section fits, add a new section with a clear heading
5. Follow the existing format of the file
6. Use code examples with CORRECT/WRONG patterns where applicable

### Step 8: Create PR to azure-messaging-ai-context

After updating `general_coding_instructions.md`, create a PR to the azure-messaging-ai-context repository with the changes:

1. **If working in azure-messaging-ai-context repo**: Create a branch and PR directly
2. **If working in a higher-level repo**: The changes are in `deps/azure-messaging-ai-context/.github/general_coding_instructions.md`. Create a PR to the [Azure/azure-messaging-ai-context](https://github.com/Azure/azure-messaging-ai-context) repository with the updated file.

### Step 9: Summarize Changes

Use this summary template to report changes:

| Category | Found | New | Skipped (dup) |
|----------|-------|-----|---------------|
| Code Style | X | Y | Z |
| Error Handling | X | Y | Z |
| Testing | X | Y | Z |
| Memory Management | X | Y | Z |

**Added to general_coding_instructions.md:** [numbered list with section name and source thread/comment IDs]

**New sections created:** [list of new section names, if any]

**Skipped (already documented):** [list with location in existing section]

Report:
- Number of new learnings added
- Sections updated (and any new sections created)
- Categories covered

## Guidelines

### What Makes a Good Learning

- **Specific**: "Use `#define` for array sizes" not "Be careful with arrays"
- **Actionable**: Shows what TO DO and what NOT to do
- **Generalizable**: Applies beyond the specific PR/file
- **Documented with examples**: Include code snippets when relevant

### Format Conventions

- Use markdown headers to organize sections
- Use code blocks with language hints (```c, ```powershell)
- Use tables for reference information
- Use CORRECT/WRONG patterns with comments