Repository navigation
Closed
Labels
type:choreMaintenance, refactoring, cleanupMaintenance, refactoring, cleanup
Description
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 withteam.md.
Scope
In scope:
- Trim
.github/copilot-instructions.mdfrom ~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.mdto eliminate duplication
Out of scope:
- Changes to
squad.agent.md(separate concern) - Changes to
team.mdGit Workflow section (can be a follow-up) - Changes to
decisions.mdsize (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
Metadata
Metadata
Assignees
Labels
type:choreMaintenance, refactoring, cleanupMaintenance, refactoring, cleanup
Activity
chore: trim copilot-instructions.md and extract protected-files skill
docs: update procedures history for #999
chore: trim copilot-instructions.md and extract protected-files skill
docs: update procedures history for #999
chore: CI cleanup — delete ci-rerun.yml, streamline squad-ci.yml (git…
chore: CI cleanup — delete ci-rerun.yml, streamline squad-ci.yml (#1000…