Skip to content

docs: simplify agent context and resolve conflicting guidance - #2287

Open
thymikee wants to merge 2 commits into
mainfrom
docs/agent-context-follow-through
Open

docs: simplify agent context and resolve conflicting guidance#2287
thymikee wants to merge 2 commits into
mainfrom
docs/agent-context-follow-through

Conversation

@thymikee

@thymikee thymikee commented Sep 5, 2026

Copy link
Copy Markdown
Member

Summary

Remove generic execution advice, basic CLI tutorials, duplicated checklists, and rhetorical explanations from contributor context. Apply the GPT-6 Astra guidance by narrowing instructions to repository-specific constraints and resolving conflicting rules.

  • Align immediate skill startup with conditional help lookup, parallel work with distinct devices, and CI requirements with selected checks.
  • Clarify publication authorization, dependent PR publication versus merge-readiness, and validation after rebasing.
  • Correct misleading gate/sandbox failure diagnoses, nonexistent depgraph-to-gate input, and pure-test-move verification. Preserve non-obvious constraint comments.

Seven context files changed. Scope covers contributor guidance; the reviewed glossary and packaged skills remain unchanged. Compared with main, AGENTS.md shrinks from 9,994 to 7,805 bytes, and root context plus routed procedures shrink 11.7%. Existing context budgets and gate definitions are unchanged.

Validation

Validated commit: 501426464c587f4efb6ff6028ba4ffc34b99821c.

Repository formatting, diff checks, referenced local-path checks, and the required affected gate passed (all four guidance contracts). The gate ran with host process-inspection access required by its harness. Manually reviewed instruction scope and cross-file consistency against the glossary, four packaged skills, and all nine routed procedures; checked affected-selector behavior against code. Documentation only, so runtime tests do not apply. CI on the updated PR head remains authoritative.

@thymikee

thymikee commented Sep 5, 2026

Copy link
Copy Markdown
Member Author

The new AGENTS.md precedence rule is unsafe: saying user instructions “take precedence over repository and skill guidance” invites agents to bypass binding repository constraints such as required gates, device/session ownership, worktree safety, and authorization boundaries.

Please narrow it: user requests define task intent and override discretionary guidance only; system/developer requirements and repository hard rules remain binding, except where a rule explicitly makes user authorization the condition for proceeding. On conflict, identify the exact constraint rather than silently bypassing it.

@thymikee thymikee changed the title docs: clarify agent task scope and validation docs: simplify agent context and resolve conflicting guidance Sep 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant