Conversation
- Added detailed relationships between Knowledge, Tests, and Best Practices in `mastg-best-practice.instructions.md`. - Clarified scope boundaries and content guidelines in `mastg-knowledge.instructions.md`. - Improved overview phrasing and linking requirements in `mastg-test.instructions.md`. - Updated best practices linkage instructions in `porting-mastg-v1-tests-to-v2.instructions.md`.
cpholguera
changed the title
Contributor
There was a problem hiding this comment.
Pull request overview
This PR enhances the clarity and consistency of documentation by clarifying scope boundaries between Knowledge, Tests, and Best Practices components, detailing their relationships, and providing more explicit guidance on content structure. The changes focus on improving authoring standards across instruction files.
- Clarifies the three-way relationship and scope boundaries between Knowledge (descriptive), Tests (issue-focused), and Best Practices (prescriptive) components
- Adds detailed guidance for writing test overviews with issue-focused framing and examples
- Expands metadata documentation to include knowledge references in best practices
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
.github/instructions/porting-mastg-v1-tests-to-v2.instructions.md |
Updates best practice linkage instructions with clearer guidance on using YAML front matter |
.github/instructions/mastg-test.instructions.md |
Adds comprehensive guidance on writing issue-focused overviews, clarifies evaluation/observation requirements, and updates profile documentation link |
.github/instructions/mastg-r2-scripts.instructions.md |
Updates scope definition with consistent quotation formatting |
.github/instructions/mastg-mitmproxy-scripts.instructions.md |
Updates scope definition with consistent quotation formatting |
.github/instructions/mastg-knowledge.instructions.md |
Expands scope boundaries section with explicit guidance on avoiding prescriptive/threat language and clarifies relationship to tests |
.github/instructions/mastg-demo.instructions.md |
Updates evaluation section with consistent quotation formatting |
.github/instructions/mastg-best-practice.instructions.md |
Adds nuanced relationship explanation between Tests, Knowledge, and Best Practices, plus knowledge metadata field |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Diolor
approved these changes
Dec 14, 2025
|
|
||
| - Describe the relevant platform feature/API from the perspective of "what can go wrong" (risk, failure mode, exposure). | ||
| - Make it clear why the test exists: what the tester is trying to detect and why that matters. | ||
| - Reference the related Knowledge page for background using its ID (for example, @MASTG-KNOW-0013). |
Collaborator
There was a problem hiding this comment.
What's the deletion motive?
Collaborator
Author
There was a problem hiding this comment.
Because now we'll rather enforce the metadata key instead.
Collaborator
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR enhances the clarity and consistency of documentation by clarifying scope boundaries between Knowledge, Tests, and Best Practices components, detailing their relationships, and providing more explicit guidance on content structure. The changes focus on improving authoring standards across instruction files.