[docs] docs: unbloat monitoring-with-projects.md#38417
Conversation
Surgical clarity pass on the experimental Monitoring with Projects guide: - Fold 4 verbose "See the full reference: [literal-url](url)" lines into clean inline links - Convert update-project and group-reports bullet lists to prose - Drop the audit code block that duplicated the preceding command bullets (folding the --count trend detail into the bullet) 141 -> 114 lines (19% line / 10% word / 50% bullet reduction). All YAML examples, reference links, and details preserved. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
🧪 Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. The only changed file is docs/src/content/docs/experimental/monitoring-with-projects.md (a documentation file). Test Quality Sentinel skipped. |
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
|
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR #38417 does not have the implementation label (has_implementation_label=false) and has 0 new lines of code in business logic directories (below the 100-line threshold, requires_adr_by_default_volume=false). |
There was a problem hiding this comment.
Pull request overview
This PR tightens and de-bloats the experimental “Monitoring with Projects” documentation, consolidating repetitive bullets and examples into shorter prose while preserving the key YAML snippets and reference links.
Changes:
- Condensed
update-project,create-project-status-update, andgroup-reportsexplanations into single-paragraph guidance with inline reference links. - Simplified the no-op reporting section by merging adjacent explanatory sentences.
- Removed redundant audit example blocks and folded the
--count 10trend detail into thegh aw logsbullet.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/experimental/monitoring-with-projects.md | Streamlines monitoring-with-projects guidance by reducing verbosity while keeping essential examples and references. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 2
| - Can also create views and custom fields when configured. | ||
|
|
||
| See the full reference: [/reference/safe-outputs/#project-board-updates-update-project](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) | ||
| Adds issues/PRs to the board and updates custom fields, and can create views and custom fields when configured. See the [`update-project` reference](/gh-aw/reference/safe-outputs/#project-board-updates-update-project). |
| # Trend report across the last 10 runs of a workflow | ||
| gh aw logs my-workflow --format markdown --count 10 | ||
| ``` | ||
| - `gh aw logs my-workflow --format markdown --count 10` — cross-run security and performance report for trend monitoring |
|
✅ smoke-ci: safeoutputs CLI comment + comment-memory run (27297178257)
|
Comment MemoryNote This comment is managed by comment memory.It stores persistent context for this thread in the code block at the top of this comment.
|
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs — approving with two minor polish suggestions.
📋 Key Themes & Highlights
Key Themes
- Vocabulary consistency:
group-reportscode reference dropped from one sentence; placeholder style inconsistency in the audit bullet list. - These are low-friction fixes; nothing blocks merge.
Positive Highlights
- ✅ All factual content preserved — the 19%/10% reductions are genuinely noise-free
- ✅ Verbose
See the full reference: [url-as-text](url)anti-pattern cleaned up consistently across all four occurrences - ✅ The duplicate bash block removal is well-justified: the three
gh aw auditexamples were already covered by the inline bullets, so the deletion is lossless - ✅ Bullet-to-prose collapses read naturally and improve scannability
- ✅ Clear, honest PR description with before/after metrics
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 170.3 AIC · ⌖ 13.5 AIC
| - Up to 64 sub-issues are tracked per parent issue. | ||
|
|
||
| See the full reference: [/reference/safe-outputs/#group-reports-group-reports](/gh-aw/reference/safe-outputs/#group-reports-group-reports) | ||
| When enabled, a parent "[aw] Failed runs" issue is automatically created and managed, and each failure report is linked as a sub-issue under it (up to 64 per parent). See the [`group-reports` reference](/gh-aw/reference/safe-outputs/#group-reports-group-reports). |
There was a problem hiding this comment.
[/grill-with-docs] The group-reports code reference is dropped from the opening phrase — When group-reports is enabled, was more precise and matches the project vocabulary used in the YAML block directly above.
💡 Suggestion
Change:
When enabled, a parent "[aw] Failed runs" issue...
To:
When `group-reports` is enabled, a parent "[aw] Failed runs" issue...
This keeps the term anchored to the config key, which is helpful for readers scanning or searching for group-reports.
| gh aw logs my-workflow --format markdown --count 10 | ||
| ``` | ||
| - `gh aw logs my-workflow --format markdown --count 10` — cross-run security and performance report for trend monitoring | ||
|
|
There was a problem hiding this comment.
[/grill-with-docs] my-workflow breaks the placeholder convention used in the two bullets above, which use <run-id> and <run-id-1>. Readers may not recognise my-workflow as a stand-in name.
💡 Suggestion
For consistency with the <run-id> style already in use, consider:
- `gh aw logs <workflow> --format markdown --count 10` — cross-run security and performance report for trend monitoring
Angle brackets signal "replace this with your value" throughout CLI docs and match the pattern the preceding bullets already use.
What
Surgical clarity pass on
docs/src/content/docs/experimental/monitoring-with-projects.md:update-projectandgroup-reportsbullet lists to flowing prose paragraphs.bashcode block that duplicated the preceding command bullets; folds the--counttrend detail back into the relevant bullet.Net result: 141 → 114 lines (19% line reduction, ~10% word reduction, ~50% bullet reduction). All YAML examples, reference links, and substantive detail are preserved.
Why
The guide had accumulated a pattern of over-bulleting and redundant reference links that made it harder to read without adding information. Prose is easier to scan for narrative sections; inline links reduce visual noise compared to standalone link-only lines.
Changes
docs/src/content/docs/experimental/monitoring-with-projects.mdImpact