fix: Broken #file: directives and markdown links after collection directory reorg #742
Description
Summary
The collection-based directory reorganization (#643) moved agents, prompts, and instructions from flat directories into {collection}/ subdirectories. However, 34 #file: directives and markdown links across 15 files were not updated to reflect the new directory depth. All broken references follow the same pattern: they use one ../ traversal when two are now required, and they omit the collection subdirectory name.
Root Cause
Before the reorg, files were structured as:
.github/prompts/github-triage-issues.prompt.md
.github/instructions/github-backlog-triage.instructions.md
A reference #file:../instructions/github-backlog-triage.instructions.md from a prompt correctly resolved to .github/instructions/github-backlog-triage.instructions.md.
After the reorg:
.github/prompts/github/github-triage-issues.prompt.md
.github/instructions/github/github-backlog-triage.instructions.md
The same reference #file:../instructions/github-backlog-triage.instructions.md now resolves to .github/prompts/instructions/github-backlog-triage.instructions.md, which does not exist.
Fix Pattern
#file:../instructions/{filename}.md → #file:../../instructions/{collection}/{filename}.md
[text](../instructions/{filename}.md) → [text](../../instructions/{collection}/{filename}.md)
Broken References
ADO Collection (7 references in 2 files)
| File | Line | Broken Reference | Correct Path |
|---|---|---|---|
.github/agents/ado/ado-prd-to-wit.agent.md |
11 | #file:../instructions/ado-wit-planning.instructions.md |
#file:../../instructions/ado/ado-wit-planning.instructions.md |
.github/prompts/ado/ado-get-build-info.prompt.md |
7 | #file:../instructions/ado-get-build-info.instructions.md |
#file:../../instructions/ado/ado-get-build-info.instructions.md |
.github/prompts/ado/ado-create-pull-request.prompt.md |
7 | #file:../instructions/ado-create-pull-request.instructions.md |
#file:../../instructions/ado/ado-create-pull-request.instructions.md |
.github/prompts/ado/ado-process-my-work-items-for-task-planning.prompt.md |
7 | #file:../instructions/ado-wit-planning.instructions.md |
#file:../../instructions/ado/ado-wit-planning.instructions.md |
.github/prompts/ado/ado-update-wit-items.prompt.md |
7 | #file:../instructions/ado-update-wit-items.instructions.md |
#file:../../instructions/ado/ado-update-wit-items.instructions.md |
.github/prompts/ado/ado-get-my-work-items.prompt.md |
7 | #file:../instructions/ado-wit-planning.instructions.md |
#file:../../instructions/ado/ado-wit-planning.instructions.md |
GitHub Collection (19 references in 6 files)
| File | Line | Broken Reference | Correct Path |
|---|---|---|---|
.github/agents/github/github-backlog-manager.agent.md |
35 | [...](../instructions/github-backlog-planning.instructions.md) |
[...](../../instructions/github/github-backlog-planning.instructions.md) |
.github/agents/github/github-backlog-manager.agent.md |
40, 41, 77, 90 | [...](../instructions/github-backlog-planning.instructions.md) (×4) |
[...](../../instructions/github/github-backlog-planning.instructions.md) |
.github/agents/github/github-backlog-manager.agent.md |
81 | [...](../instructions/github-backlog-triage.instructions.md) |
[...](../../instructions/github/github-backlog-triage.instructions.md) |
.github/agents/github/github-backlog-manager.agent.md |
82 | [...](../instructions/github-backlog-discovery.instructions.md) |
[...](../../instructions/github/github-backlog-discovery.instructions.md) |
.github/agents/github/github-backlog-manager.agent.md |
84, 85 | [...](../instructions/github-backlog-update.instructions.md) (×2) |
[...](../../instructions/github/github-backlog-update.instructions.md) |
.github/prompts/github/github-triage-issues.prompt.md |
10 | #file:../instructions/github-backlog-triage.instructions.md |
#file:../../instructions/github/github-backlog-triage.instructions.md |
.github/prompts/github/github-triage-issues.prompt.md |
11 | #file:../instructions/github-backlog-planning.instructions.md |
#file:../../instructions/github/github-backlog-planning.instructions.md |
.github/prompts/github/github-add-issue.prompt.md |
11 | #file:../instructions/github-backlog-planning.instructions.md |
#file:../../instructions/github/github-backlog-planning.instructions.md |
.github/prompts/github/github-discover-issues.prompt.md |
11 | #file:../instructions/github-backlog-discovery.instructions.md |
#file:../../instructions/github/github-backlog-discovery.instructions.md |
.github/prompts/github/github-discover-issues.prompt.md |
12 | #file:../instructions/github-backlog-planning.instructions.md |
#file:../../instructions/github/github-backlog-planning.instructions.md |
.github/prompts/github/github-execute-backlog.prompt.md |
11 | #file:../instructions/github-backlog-update.instructions.md |
#file:../../instructions/github/github-backlog-update.instructions.md |
.github/prompts/github/github-execute-backlog.prompt.md |
12 | #file:../instructions/github-backlog-planning.instructions.md |
#file:../../instructions/github/github-backlog-planning.instructions.md |
.github/prompts/github/github-sprint-plan.prompt.md |
11 | #file:../instructions/github-backlog-planning.instructions.md |
#file:../../instructions/github/github-backlog-planning.instructions.md |
.github/prompts/github/github-sprint-plan.prompt.md |
13 | [...](../instructions/github-backlog-discovery.instructions.md) |
[...](../../instructions/github/github-backlog-discovery.instructions.md) |
.github/prompts/github/github-sprint-plan.prompt.md |
15 | [...](../instructions/github-backlog-triage.instructions.md) |
[...](../../instructions/github/github-backlog-triage.instructions.md) |
HVE-Core Collection (3 references in 3 files)
| File | Line | Broken Reference | Correct Path |
|---|---|---|---|
.github/prompts/hve-core/git-commit-message.prompt.md |
8 | #file:../instructions/commit-message.instructions.md |
#file:../../instructions/hve-core/commit-message.instructions.md |
.github/prompts/hve-core/git-commit.prompt.md |
8 | #file:../instructions/commit-message.instructions.md |
#file:../../instructions/hve-core/commit-message.instructions.md |
.github/prompts/hve-core/git-merge.prompt.md |
8 | #file:../instructions/git-merge.instructions.md |
#file:../../instructions/hve-core/git-merge.instructions.md |
Acceptance Criteria
- All 34 broken
#file:directives and markdown links are updated with correct paths -
npm run lint:allpasses -
npm run plugin:generatesucceeds - Manual verification that
#file:directives resolve in VS Code after the fix
Related Issues
- feat: Reorganize agents, instructions, prompts, and skills into collection-based subdirectories #643 — Reorganize artifacts into collection-based subdirectories (the reorg that caused these breaks)
- fix: AI generated .copilot-tracking files produce broken relative paths flooding VS Code Problems tab #698 — Generated
.copilot-trackingfiles produce broken relative paths (related path portability)