Skip to content

Trim .github/copilot-instructions.md to reduce attention dilution #999

Closed

Description

@bradygaster

Problem

.github/copilot-instructions.md has grown to ~2,250 tokens (~9KB, 155 lines). This file is injected into every Copilot coding agent session. At 1.5–4.5× the comfortable ceiling for an always-injected instruction file, it is likely causing attention dilution and inconsistent agent behavior.

Evidence (from Flight analysis)

Bloat sources

Section Tokens Issue
Protected Files ~440 Applies to 5 specific files but loaded in every session. Should be an on-demand skill.
Git Safety — Branch Contamination ~150 Repeats staging rules already stated elsewhere + introduces a 3rd contradictory branch-creation command
Sweeping Refactor Rules ~130 Rare task type, overlaps with Protected Files
Changeset format block ~60 6 lines for what could be 1 sentence

Misbehavior mechanisms

  • Attention dilution — Critical workflow instructions (Team Context, Capability Check) are buried in the middle where LLMs attend weakest. Defensive rules dominate the top.
  • Contradictory commands — Three different "create a feature branch" commands across copilot-instructions.md + team.md. Agent picks whichever gets more attention weight that session.
  • Over-caution — "STOP and Ask" on >20 files or any deletions may stall legitimate refactors.
  • Duplication — ~470 tokens duplicated with .squad/copilot-instructions.md, ~90 tokens with team.md.

Scope

In scope:

  • Trim .github/copilot-instructions.md from ~2,250 tokens → ~800–1,000 tokens
  • Extract Protected Files content to an on-demand skill (.copilot/skills/protected-files/SKILL.md)
  • Consolidate Git Safety to remove internal repetition and resolve the contradictory branch-creation commands
  • Compact the Changeset Requirement section
  • Reorder remaining sections so essential workflow instructions come first (where attention is strongest)
  • Reconcile with .squad/copilot-instructions.md to eliminate duplication

Out of scope:

  • Changes to squad.agent.md (separate concern)
  • Changes to team.md Git Workflow section (can be a follow-up)
  • Changes to decisions.md size (separate concern)

Acceptance criteria

  • File is ≤1,000 tokens (measure with a token counter)
  • Protected Files content lives in a skill file, referenced by a single-line pointer
  • No contradictory branch-creation commands remain
  • Essential workflow sections (Team Context, Capability Self-Check, Branch Naming) appear near the top
  • Existing tests pass (npm run test)
  • Template sync tests pass (if copilot-instructions.md is part of the template sync)
  • Copilot coding agent can still correctly: create branches, open PRs, respect protected files, include changesets

Activity

  1. added 4 commits that reference this issue on Apr 18, 2026
    74bb2ba
    9545b4a
    a8faed1
    6c03988
  2. added a commit that references this issue on Apr 18, 2026
    7b4ba79
  3. added a commit that references this issue on Apr 21, 2026
    37ab248
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    type:choreMaintenance, refactoring, cleanup

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions