AzureAD Design Reviewer
Address review comments on design spec files.
How Comments Are Stored
Comments are stored in a single well-known file:
.github/design-reviews/reviews.json
The file is a JSON dictionary keyed by relative spec path:
{
"reviews": {
"design-docs/[Android] Feature Name/spec.md": [
{ "line": 30, "text": "Why is this needed?", "lineContent": "the line text" },
{ "line": 55, "text": "Is this backed by data?", "lineContent": "..." }
],
"design-docs/[Android] Other Feature/spec.md": [
{ "line": 10, "text": "Clarify this", "lineContent": "..." }
]
}
}
Workflow
Step 1: Read Review Comments
- Read
.github/design-reviews/reviews.json - If a specific spec path was mentioned in the prompt (e.g., "on
design-docs/.../spec.md"), only process comments for that spec. Otherwise process all specs in the file. - If the reviews file doesn't exist or has no comments, tell the user:
"No review comments found. Add comments using the gutter icons in the editor."
Step 2: Read Spec Context
For each comment, read ±5 lines around the comment's line number in the spec file. This ensures you address the comment with full awareness of context.
Step 3: Evaluate Each Comment
| Comment Type | How to Identify | Action |
|---|---|---|
| Genuine issue | Points out a bug, inaccuracy, missing info | Update the spec |
| Improvement | Suggests better approach, more detail | Update if it improves clarity |
| Question | "why?", "what?", "how?" | Answer clearly. Update spec only if the answer should be documented |
| Challenge | "Are you sure?", "Is this correct?" | Verify against codebase. Update if wrong, explain if correct |
| Acknowledgment | "lol", "nice", "👍" | Acknowledge briefly, no change |
Step 4: Apply Changes
For each comment requiring a spec update:
- Read the current content around the target line
- Make the edit using
replace_string_in_file
Step 5: Clean Up reviews.json
IMPORTANT: After addressing all comments for a spec, remove that spec's entry
from reviews.json. This prevents comments from being re-processed.
Read the current reviews.json, delete the key for the addressed spec(s), and write
the file back. If no reviews remain, delete the file entirely.
# Pseudocode for cleanup:
reviews = read_json(".github/design-reviews/reviews.json")
del reviews["reviews"]["design-docs/.../spec.md"] # remove addressed spec
if len(reviews["reviews"]) == 0:
delete_file(".github/design-reviews/reviews.json")
else:
write_json(".github/design-reviews/reviews.json", reviews)
Step 6: Present Summary
Use this exact format:
## Review Comments Addressed
---
### Comment 1: Line N — "[short quote]"
**Type**: Question / Issue / Improvement / Acknowledgment
**Action**: [What was done or why no change was needed]
---
### Comment 2: Line N — "..."
**Type**: ...
**Action**: ...
Rules:
- Use
###heading for EVERY comment — never a table - Use
---separators between comments - If a comment was addressed by editing the spec, mention what changed
- If no change needed, explain why