| 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. Use when this capability is needed. |
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):
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
# 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.
Source: Azure/azure-sdk-tools — distributed by TomeVault.
