Skip to content
This repository is currently being migrated. It's locked while the migration is in progress.

Commit ddb8b20

Browse files
Adds guidance-grooming skill and Copilot coding agent instructions (#5720)
* feat: Add guidance-grooming skill and Copilot coding agent instructions - New skill: guidance-grooming bridges doc-queue and writing-vads-guidance - Updates doc-queue Step 3 to use grooming skill instead of inline analysis - Updates writing-vads-guidance to consume grooming comments - Adds Copilot coding agent section to copilot-instructions.md - Adds grooming comment edit-in-place pattern (single source of truth) - Adds --body-file guidance to AGENTS.md for gh CLI markdown content - Registers all 3 skills in AGENTS.md Available Workflows * fix: Use -F body=@file for gh api PATCH to avoid shell escaping Addresses PR review feedback — uses gh api's native @file syntax instead of command substitution with $(cat ...) for robustness with arbitrary markdown content.
1 parent a7605a2 commit ddb8b20

5 files changed

Lines changed: 534 additions & 61 deletions

File tree

.claude/skills/doc-queue/SKILL.md

Lines changed: 11 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -166,70 +166,18 @@ gh issue edit <ISSUE_NUMBER> --repo department-of-veterans-affairs/vets-design-s
166166

167167
This signals to the team that someone is actively working on the issue.
168168

169-
## Step 3: Analyze Selected Issue
169+
## Step 3: Groom the Issue
170170

171-
### Fetch Full Issue Details
171+
**REQUIRED SUB-SKILL:** Use guidance-grooming to analyze and prepare the issue for writing.
172172

173-
```bash
174-
gh issue view <ISSUE_NUMBER> --repo department-of-veterans-affairs/vets-design-system-documentation \
175-
--json title,body,labels,comments,assignees | cat
176-
```
177-
178-
### Issue Analysis Checklist
179-
180-
For each issue, determine:
181-
182-
1. **Issue Type:**
183-
- [ ] New documentation needed
184-
- [ ] Update existing documentation
185-
- [ ] Fix incorrect information
186-
- [ ] Add examples/code samples
187-
- [ ] Accessibility guidance update
188-
- [ ] Design decision documentation
189-
190-
2. **Affected Files:**
191-
- Identify which documentation files need changes
192-
- Search codebase for related content:
193-
```bash
194-
# For component issues (e.g., va-alert)
195-
find src/_components -name "*alert*" -type f
196-
197-
# For pattern issues
198-
find src/_patterns -name "*.md" -type f | xargs grep -l "KEYWORD"
199-
```
200-
201-
3. **Dependencies:**
202-
- Does this require component-library changes?
203-
- Does this need design review?
204-
- Are there related issues to reference?
205-
206-
4. **Scope Assessment:**
207-
- Small: Single file update, minor text changes
208-
- Medium: Multiple sections or files, new examples needed
209-
- Large: New page creation, significant restructuring
173+
The guidance-grooming skill will:
174+
- Fetch full issue details and identify affected files
175+
- Analyze completeness against the required information checklist
176+
- Prompt you for any missing context or design decisions
177+
- Post a structured `## Grooming Summary` comment on the issue
178+
- Apply the `groomed` label
210179

211-
### Present Summary to User
212-
213-
Format the analysis as:
214-
215-
---
216-
**Issue #[NUMBER]: [TITLE]**
217-
218-
**Summary:** [2-3 sentence summary of what needs to be done]
219-
220-
**Type:** [Issue type from checklist]
221-
222-
**Files to modify:**
223-
- `path/to/file1.md` - [what changes needed]
224-
- `path/to/file2.md` - [what changes needed]
225-
226-
**Scope:** [Small/Medium/Large]
227-
228-
**Questions for you:**
229-
1. [Any clarifying questions based on issue analysis]
230-
2. [Design decisions that need input]
231-
232-
---
180+
**Skip this step** if the issue already has a `## Grooming Summary` comment in its comments — it's already been groomed.
233181

234182
## Step 4: Reference Contributing Guide
235183

@@ -286,6 +234,8 @@ web-component: va-component-name
286234

287235
## Step 5: Execute Documentation Updates
288236

237+
**Prerequisite:** The issue must have a `## Grooming Summary` comment (from Step 3) before proceeding. The grooming comment is the authoritative work order for this step.
238+
289239
**REQUIRED SUB-SKILL:** Use writing-vads-guidance for all documentation changes.
290240

291241
The writing-vads-guidance skill provides detailed guidance on:

0 commit comments

Comments
 (0)