---
name: report-architect-comments
description: "Retrieve human architect review comments from APIView for a date range. Use for: architect comments, human comments, reviewer comments, board comments, architect comments for March, what did architects say, human review comments."
argument-hint: "Month name (e.g. 'March') or language + month (e.g. 'Python for March')"
---

# Report Architect Comments

## When to Use
- Reviewing what human architects (language board approvers) commented on during a period
- Analyzing review themes or patterns from human reviewers
- Comparing human review feedback against AI-generated comments
- Understanding what architects focus on for a specific language

## Understanding Architect Comments

This command returns comments written by **human language board approvers** in APIView. It excludes:
- **Diagnostic** comments (auto-generated by tooling)
- **AIGenerated** comments (written by APIView Copilot)
- **Deleted** comments

The set of approvers is determined from the APIView Permissions container — members of groups whose roles include "Architect" or "Deputy Architect" for the specified language. When no language is specified, all architect and deputy-architect group members are included.

Use `--all-commenters` to skip approver filtering and return comments from all users.

## Defaults

Unless the user says otherwise, always apply these defaults:
- **Environment**: `production`
- **Language**: All languages (do not pass `--language` unless user specifies one)
- **Format**: JSON (do not pass `--format`)

## Date Resolution

The user will typically specify a calendar month by name (e.g. "March", "January 2025"). Resolve to the full month date range:

| User says | start_date | end_date |
|-----------|-----------|----------|
| "March" (current year) | `YYYY-03-01` | `YYYY-03-31` |
| "January 2025" | `2025-01-01` | `2025-01-31` |
| "March 1 to March 15" | `YYYY-03-01` | `YYYY-03-15` |

When only a month name is given without a year, use the current year. Be careful with month lengths (28/29/30/31 days).

## Running the Command

### Step 1: Run the Command

Show the resolved command and run it immediately in a **foreground terminal** with a **120-second timeout** (`timeout: 120000`). Redirect to a file since output can be very large.

**Full terminal command** (cleanup + run):
```powershell
New-Item -ItemType Directory -Path output -Force | Out-Null; if (Test-Path output/architect_comments_output.json) { Remove-Item output/architect_comments_output.json }; python cli.py report architect-comments -s <start_date> -e <end_date> | Out-File -Encoding UTF8 output/architect_comments_output.json
```

After the command completes, **read the output file** with `read_file` to get the JSON results. Summarize the findings for the user (total count, languages covered, common themes, etc.).

### Step 2: Answer Follow-up Questions

For follow-up questions about the same data (filtering, counting, searching), **read the output file** with `read_file` instead of re-running the command. The file is at `output/architect_comments_output.json`.

### Examples

```powershell
# All architect comments for March 2026
python cli.py report architect-comments -s 2026-03-01 -e 2026-03-31

# Python architect comments only
python cli.py report architect-comments -s 2026-03-01 -e 2026-03-31 -l python

# All commenters (not just approvers)
python cli.py report architect-comments -s 2026-03-01 -e 2026-03-31 -l python --all-commenters

# Include reply comments (by default only first comment per thread is returned)
python cli.py report architect-comments -s 2026-03-01 -e 2026-03-31 -l java --include-replies

# YAML output
python cli.py report architect-comments -s 2026-03-01 -e 2026-03-31 --format yaml

# Staging environment
python cli.py report architect-comments -s 2026-03-01 -e 2026-03-31 --environment staging
```

## Available Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--start-date` / `-s` | string | required | Start date (`YYYY-MM-DD`) |
| `--end-date` / `-e` | string | required | End date (`YYYY-MM-DD`) |
| `--language` / `-l` | string | all | Language to filter by (e.g., `python`, `Go`, `C#`) |
| `--environment` | string | `production` | `production` or `staging` |
| `--format` / `-f` | string | `json` | Output format: `json` or `yaml` |
| `--all-commenters` | flag | `false` | Include comments from all users, not just approvers |
| `--include-replies` | flag | `false` | Include reply comments. By default only the first comment per thread is returned |

## Gotchas

- **Output can be large**: Redirect to file and use `read_file` rather than relying on terminal output.
- **Date range filters by thread start time**: Only threads whose first comment falls within the date window are included. A reply created during the window is excluded if the thread itself started before the window.
- **Use `python cli.py` not `.\avc`**: The `avc.bat` script may resolve to system Python.
- **Do NOT use `2>&1`**: Merges stderr into stdout, corrupting JSON. Only redirect stdout.
- **Do NOT use `>`**: Produces UTF-16 in PowerShell 5.1. Use `| Out-File -Encoding UTF8`.
- **Month end dates**: February has 28/29 days, April/June/Sept/Nov have 30 days.
- **Approver filtering**: If no approvers are found for a language, no comments are returned. This can happen for less common languages with no registered board members.