Skip to content

docs: clarify large artifact context tooling #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tomcasaburi wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: clarify large artifact context tooling #63

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,10 @@ Routine live operations are not repository feature work:
- **MUST** ask before creating any public GitHub artifact when a task could be interpreted as either repository work or live operations.
- **MUST NOT** include private infrastructure details, secrets, API keys, or user-specific operational data in GitHub issues, comments, PRs, or commit messages.

## AI Context Tools

For very large non-source artifacts such as CI logs, debug traces, generated JSON, or massive command output, agents may optionally use `chopratejas/headroom` or a similar local compression tool as a navigation aid, but must verify conclusions against the original uncompressed artifact before editing code or making final claims.
Comment on lines +84 to +86

@coderabbitai coderabbitai Bot Jun 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Placement inconsistency: Section should likely be under "Core MUST Rules".

The PR description states this guidance is added "under 'Core MUST Rules'", but the actual implementation places it as a sibling section before "Core MUST Rules" (line 88). Additionally, the content contains a MUST-level requirement ("must verify conclusions") but is placed outside the "Core MUST Rules" section.

Consider either:

  1. Moving this subsection under "Core MUST Rules" as a ### subsection (matching the PR description), or
  2. Restructuring to separate the optional suggestion (using compression tools) from the mandatory requirement (verification before final claims)
📝 Proposed fix: Move under Core MUST Rules as a subsection 
-## AI Context Tools
-
-For very large non-source artifacts such as CI logs, debug traces, generated JSON, or massive command output, agents may optionally use `chopratejas/headroom` or a similar local compression tool as a navigation aid, but must verify conclusions against the original uncompressed artifact before editing code or making final claims.
-
 ## Core MUST Rules
 
+### AI Context Tools
+
+- **MAY** optionally use `chopratejas/headroom` or a similar local compression tool as a navigation aid for very large non-source artifacts such as CI logs, debug traces, generated JSON, or massive command output.
+- **MUST** verify conclusions against the original uncompressed artifact before editing code or making final claims.
+
 ### Environment Setup

This aligns with the PR description and separates the optional (MAY) from mandatory (MUST) guidance using the priority levels defined in the document.

🧰 Tools
🪛 LanguageTool

[style] ~86-~86: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...mit messages. ## AI Context Tools For very large non-source artifacts such as CI logs, d...

(EN_WEAK_ADJECTIVE)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@AGENTS.md` around lines 84 - 86, The "AI Context Tools" paragraph is placed
before the "Core MUST Rules" section but contains a MUST-level requirement; move
this paragraph under the "Core MUST Rules" header as a ### subsection named "AI
Context Tools" (or split it into two sentences under "AI Context Tools": one MAY
sentence recommending compression tools and a separate MUST sentence requiring
verification of conclusions against the original artifact) so the mandatory
language lives inside "Core MUST Rules" and the optional guidance remains
clearly marked as MAY.


## Core MUST Rules

### Environment Setup
Expand Down