You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+45-2Lines changed: 45 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -103,7 +103,7 @@ Do not modify fixed template fields.
103
103
104
104
If `multi_install` is set to true, the first page must act as an overview for the series. Sub-pages must set `multitool_install_part: true`.
105
105
106
-
### Required content structure
106
+
####Required content structure
107
107
108
108
Install guides should include:
109
109
@@ -127,7 +127,7 @@ Install guides should include:
127
127
Optional:
128
128
- Uninstall instructions
129
129
130
-
### Scope boundaries
130
+
####Scope boundaries
131
131
132
132
Install guides must not include:
133
133
- End-to-end workflows
@@ -137,6 +137,14 @@ Install guides must not include:
137
137
138
138
Learning Paths may link to install guides for setup steps. Install guides should not duplicate workflow content.
139
139
140
+
#### Tool versions
141
+
142
+
When providing commands for downloading or installing software, use a specific version in the example. This ensures that the instructions are accurate and verifiable. However, also include a note before the commands that tells readers the same commands work with other versions. Provide a link to where the latest version can be found. The note can be formatted as follows:
143
+
144
+
{{% notice Note %}}
145
+
The following commands use <tool> version <version>. The same commands work with other versions. Replace the file used in these steps with the file for your version of choice. To find the latest version, see [Link to page with release info](URL).
146
+
{{% /notice %}}
147
+
140
148
### Further reading curation
141
149
142
150
Limit `further_reading` resources to four to six essential links. Prioritize:
@@ -246,6 +254,7 @@ When adding or revising `description` fields:
246
254
- Use visual breaks to prevent walls of text. Code blocks count as visual breaks
247
255
- If you explain three or more things in one section, split it into separate sections
248
256
- Each code block should be preceded by one to three sentences explaining what it does
257
+
- If a section is long because of code or output rather than explanation, do not treat length alone as a readability problem
249
258
- For Learning Paths, include a short recap and forward-looking transition at the end of each major instructional section or module
250
259
251
260
Example recap pattern for Learning Paths:
@@ -287,10 +296,16 @@ Use these preferred terms and phrases for consistency:
287
296
- `therefore`instead of `ergo`
288
297
- `namely`instead of `viz.`
289
298
- `avoid`instead of `try not to`
299
+
- `such as`instead of `like`
300
+
- `after`instead of `once`
301
+
- `setup`as a noun, `set up` as a verb
290
302
291
303
- Avoid condescending language:
292
304
- Do not use `simply`, `just`, `obviously`, or `clearly`
293
305
306
+
- Avoid using directions when referring to content that's been referenced previously or will be referenced next:
307
+
- Do not use `above`, `below`, `left`, `right`, `top`, or `bottom`
308
+
294
309
- Acknowledge difficulty naturally:
295
310
- Use phrases like `this step can be confusing at first`
296
311
@@ -686,6 +701,34 @@ Learning Paths should optimize for selection, not ranking.
686
701
687
702
If an AI agent were asked to complete this task, the Learning Path should be the safest source to select.
688
703
704
+
### LLM review efficiency and chunking
705
+
706
+
When reviewing content, assess whether the file is suitable for efficient single-pass LLM review.
707
+
708
+
- Classify the file as prose-heavy, mixed, or code-heavy
709
+
- If a file is code-heavy, prioritize the instructional prose around the code and comment on code only when it affects correctness, usability, safety, or task success
710
+
- Do not recommend chunking purely because a file is long if most of the length comes from code blocks, commands, configuration, logs, or generated output
711
+
- Recommend chunking when a file contains multiple distinct instructional sections, conceptual units, or task phases that should be reviewed independently
712
+
- Suggest chunk boundaries using existing headings, task transitions, or conceptual breaks
713
+
- Prefer semantic chunking over fixed-size chunking
714
+
- Flag repeated boilerplate, oversized code blocks, long pasted terminal output, duplicated examples, or verbose configuration that add token cost without improving learning value
715
+
- Flag sections where code or output could be shortened to a representative example without losing instructional value
716
+
- If a file is large but structurally simple, recommend prose-first review rather than chunking
717
+
- Review by exception, not by coverage: do not comment on code, output, or prose that is already clear, correct, and fit for purpose
718
+
719
+
### Token-efficiency review priorities
720
+
721
+
When identifying content that is expensive for LLM-based review or editing, check for:
722
+
723
+
- Long fenced code blocks that are not explained or are only loosely tied to the surrounding task
724
+
- Large blocks of terminal output where a short representative excerpt would be enough
725
+
- Repeated setup or verification steps across files
726
+
- Front matter, boilerplate, or repeated notes that appear unchanged across multiple pages
727
+
- Multiple examples that teach the same point with little added value
728
+
- Sections that combine too many concepts and would review better as separate chunks
729
+
730
+
When these patterns appear, flag them as token-heavy content and explain whether they should be trimmed, condensed, or reviewed separately.
731
+
689
732
### Performance and Arm acceleration integrity
690
733
691
734
For Learning Paths that demonstrate Arm-specific performance features (for example SME2, SVE2, I8MM, DotProd, optimized microkernels), apply the following standards.
0 commit comments