department-of-veterans-affairs/doc-queue

Documentation Queue Processing Skill

Overview

This skill helps designers efficiently process documentation and guidance update issues from the VA Design System quarterly epics. It fetches the oldest unresolved issue, analyzes requirements, and guides the designer through completing the work.

Announce at start: "I'm using the doc-queue skill to help you process documentation issues from the quarterly epic."

When to Use

Use this skill when:

• A designer asks to work on guidance or documentation issues
• Someone wants to process the documentation queue
• Working through documentation backlog tickets
• Closing out doc tickets for the quarter

Trigger phrases:

• "work on documentation issues"
• "process doc queue"
• "close out guidance tickets"
• "work on VADS documentation"
• "help with documentation backlog"

Step 0: Get User's GitHub Username

Before starting, ask for the user's GitHub username if not already known:

Question: "What is your GitHub username? (This is needed to assign issues to you)"

Store this for:

• Assigning issues when work begins
• Filtering out issues already assigned to the user
• Crediting work in commits

Step 1: Locate the Documentation Epic

Primary Epic (Current Quarter)

First, try to fetch the current quarterly documentation epic:

# Get current fiscal quarter and year
# Federal fiscal year: Q1=Oct-Dec, Q2=Jan-Mar, Q3=Apr-Jun, Q4=Jul-Sep
# Fiscal year starts October 1, so calendar year Oct-Dec is FY+1

# Fetch the known epic for Q1 2026
gh issue view 5410 --repo department-of-veterans-affairs/vets-design-system-documentation --json state,title,number | cat

If epic #5410 is CLOSED, search for the next quarterly epic:

# Calculate current fiscal quarter (FY starts October)
# Q1: Oct-Dec, Q2: Jan-Mar, Q3: Apr-Jun, Q4: Jul-Sep

gh issue list --repo department-of-veterans-affairs/vets-design-system-documentation \
  --search "is:issue is:open \"Documentation updates to VADS\" in:title" \
  --label "Epic" \
  --json number,title,state \
  --limit 5 | cat

Fallback 1: Documentation Label Issues

If no open epic is found, fall back to the oldest issues with the documentation-design.va.gov label:

gh issue list --repo department-of-veterans-affairs/vets-design-system-documentation \
  --label "documentation-design.va.gov" \
  --state open \
  --json number,title,createdAt,assignees \
  --limit 20 | cat | jq 'sort_by(.createdAt) | .[0:10]'

If issues are found, proceed to Step 2 (Issue Selection) with these results.

Fallback 2: Guidance Label Issues

If no documentation-design.va.gov issues are found, search for guidance-related issues:

# Try guidance-update label first
gh issue list --repo department-of-veterans-affairs/vets-design-system-documentation \
  --label "guidance-update" \
  --state open \
  --json number,title,createdAt,assignees \
  --limit 20 | cat | jq 'sort_by(.createdAt) | .[0:10]'

# If none, try guidance-new label
gh issue list --repo department-of-veterans-affairs/vets-design-system-documentation \
  --label "guidance-new" \
  --state open \
  --json number,title,createdAt,assignees \
  --limit 20 | cat | jq 'sort_by(.createdAt) | .[0:10]'

If issues are found with either label, proceed to Step 2 (Issue Selection) with these results.

Fallback 3: Ask User for Epic/Issue URL

If no issues are found through any of the above methods, ask the user:

Question: "I couldn't find any open documentation or guidance issues. Please provide either:

1. A URL to a documentation epic to pull issues from
2. A URL to a specific documentation issue to work on"

Accept formats:

• https://github.com/department-of-veterans-affairs/vets-design-system-documentation/issues/XXXX
• Issue number only: #XXXX or XXXX

Issue Discovery Priority Summary

1. Primary: Current quarterly epic (#5410 or search for "Documentation updates to VADS Q[N] [YEAR]")
2. Fallback 1: Oldest issues with documentation-design.va.gov label
3. Fallback 2: Oldest issues with guidance-update or guidance-new labels
4. Fallback 3: Ask user for epic/issue URL

Step 2: Select Issue from Queue

Fetch Documentation Issues

Get all open documentation issues, sorted by creation date (oldest first):

gh issue list --repo department-of-veterans-affairs/vets-design-system-documentation \
  --label "documentation-design.va.gov" \
  --state open \
  --json number,title,createdAt,labels,assignees \
  --limit 50 | cat | jq 'sort_by(.createdAt)'

Selection Priority

1. Oldest unassigned issue - Issues with no assignees get priority
2. Issues with component labels (e.g., va-alert, va-button) - More scoped work
3. Issues without complex dependencies - Can be completed independently

Present Options to User

Show the 5 oldest issues and ask which one to work on:

Question header: "Select issue" Question: "Here are the 5 oldest documentation issues. Which would you like to work on?"

Options:

1. [Oldest issue title] (#number - created date)
2. [Second oldest] (#number - created date)
3. [Third oldest] (#number - created date)
4. [Fourth oldest] (#number - created date)
5. [Fifth oldest] (#number - created date)

Allow "Other" for user to specify a different issue number.

Claim the Issue

Once the user selects an issue, immediately assign it to them:

gh issue edit <ISSUE_NUMBER> --repo department-of-veterans-affairs/vets-design-system-documentation --add-assignee "<GITHUB_USERNAME>"

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

Step 3: Groom the Issue

REQUIRED SUB-SKILL: Use guidance-grooming to analyze and prepare the issue for writing.

The guidance-grooming skill will:

• Fetch full issue details and identify affected files
• Analyze completeness against the required information checklist
• Prompt you for any missing context or design decisions
• Post a structured ## Grooming Summary comment on the issue
• Apply the groomed label

Skip this step if the issue already has a ## Grooming Summary comment in its comments — it's already been groomed.

Step 4: Reference Contributing Guide

Before making documentation changes, fetch and review the contributing guide:

WebFetch: https://design.va.gov/about/contributing-to-the-design-system/contributing-to-docs
Prompt: Extract documentation guidelines including file organization, front matter requirements, formatting standards, and style guidance.

Key Documentation Standards

File Organization:

• Components: src/_components/[component-name]/index.md or src/_components/[component-name].md
• Patterns: src/_patterns/[category]/[pattern-name].md (for example, ask-users-for or help-users-to)
• Templates: src/_templates/[template-name]/index.md

Front Matter Required Fields:

---
layout: component  # or pattern, template
title: Component Name
permalink: /components/component-name/
intro-text: "Brief description of the component"
web-component: va-component-name
# Additional fields as needed
---

Content Sections (typical order):

1. Examples (with Storybook embeds)
2. Usage guidance
3. Code usage
4. Content considerations
5. Accessibility considerations
6. Related components/patterns
7. Component checklist

Storybook Embed Format:

{% include storybook-preview.html story="uswds-va-component--variant" link_text="description" %}

Image Include Format:

{% include component-example.html alt="Description" file="/images/path/file.png" %}

Style Guidelines:

• Use title case for component/pattern names
• Define acronyms on first use
• Include AKA sections for alternative names
• Hyperlink component references: Alert

Step 5: Execute Documentation Updates

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.

REQUIRED SUB-SKILL: Use writing-vads-guidance for all documentation changes.

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

• Template compliance for components, patterns, and templates
• Required Jekyll includes (Storybook, images, code props)
• VADS style standards and permitted deviations
• Handling template deviations with designer approval
• Quality checklist for documentation

Preflight Checks

Before making changes:

1. ⚠️ CRITICAL: Verify branch status and create new branch from main:

   Always check the current branch before starting work on a new issue. Each issue should have its own dedicated branch created from an up-to-date main branch.

   # First, check current branch and status
   git status && git branch
   
   # Switch to main and pull latest changes
   git checkout main
   git pull origin main
   
   # Create a new branch for this specific issue
   git checkout -b docs/issue-<NUMBER>-<short-description>
   

   Why this matters: Committing work for one issue onto another issue's branch causes confusion, requires cherry-picking to fix, and can delay PR reviews.

2. Read existing file(s) to understand current state:

   # Use Read tool on identified files
   

3. Confirm approach with user if there are multiple ways to address the issue.

4. Hand off to writing-vads-guidance skill for all documentation changes.

Step 6: Complete and Submit

Local Verification

1. Build the site locally:

   yarn build
   

2. Check for build errors - resolve any Jekyll or Gulp errors

3. Preview changes (optional):

   yarn start
   # Visit localhost:4000 to verify changes
   

Commit Changes

git add -A
git commit -m "docs: [brief description of changes]

Closes #<ISSUE_NUMBER>"

Create Pull Request

gh pr create \
  --title "docs: Short summary of changes" \
  --body "## Summary
- [Bullet points of changes made]

## Issue
Closes #<ISSUE_NUMBER>

## Testing
- [ ] Site builds without errors
- [ ] Changes render correctly on localhost
- [ ] Links are functional
- [ ] Storybook embeds work

## Screenshots
[If visual changes, include before/after]
" \
  --base main

Update Project Board Status

After creating the PR, update the issue's status in the project board to "PR Review":

# Step 1: Get the issue's project item ID
gh api graphql -f query='
query($owner: String!, $repo: String!, $number: Int!) {
  repository(owner: $owner, name: $repo) {
    issue(number: $number) {
      projectItems(first: 10) {
        nodes {
          id
          project { title id }
        }
      }
    }
  }
}' -f owner="department-of-veterans-affairs" -f repo="vets-design-system-documentation" -F number=<ISSUE_NUMBER> | cat

# Step 2: Update the status field to "PR Review"
# Replace the placeholder IDs with values from Step 1 and your project's field configuration
gh api graphql -f query='
mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
  updateProjectV2ItemFieldValue(input: {
    projectId: $projectId
    itemId: $itemId
    fieldId: $fieldId
    value: { singleSelectOptionId: $optionId }
  }) {
    projectV2Item { id }
  }
}' \
  -f projectId="<PROJECT_ID>" \
  -f itemId="<ITEM_ID_FROM_STEP_1>" \
  -f fieldId="<STATUS_FIELD_ID>" \
  -f optionId="<PR_REVIEW_OPTION_ID>" | cat

# The "Design System & Forms" project uses these status options:
# - "Backlog", "Ready", "In Progress", "PR Review", "Done"

Note: If automated project board updates fail, manually update the issue status in the GitHub project board to "PR Review".

Post-Completion

1. Notify user of PR URL

2. Confirm project board was updated to "PR Review" status

3. Ask if they want to work on another issue:

   • "PR created! Would you like to pick up another documentation issue from the queue?"

4. Track progress:

   • Note that one issue has been addressed toward the 10% quarterly goal

Error Handling

Common Issues and Resolutions

Epic not found:

• Search with broader terms
• Ask user for direct URL
• Check if epic label was changed

No open documentation issues:

• Congratulate team on clearing the queue!
• Ask if user wants to work on a different type of issue

Issue requires component-library changes:

• Inform user this issue needs development work first
• Suggest documenting what exists and creating a follow-up issue
• Skip to next documentation-only issue

Issue is blocked by design decisions:

• Present the decision needed to the user
• If user can't decide, mark issue as needing design review
• Move to next issue

Build failures after changes:

• Review error messages
• Check for syntax errors in Liquid templates
• Verify front matter YAML is valid
• Ensure file paths in includes are correct

Escalation Path

If the skill cannot resolve an issue:

1. Summarize what was attempted
2. Identify the blocker
3. Suggest next steps (e.g., "This needs input from [team/person]")
4. Offer to move to the next issue in queue

Quick Reference

Fiscal Year Quarters (Federal)

| Quarter | Months | Example | |---------|--------|---------| | Q1 | October - December | Q1 FY2026 = Oct-Dec 2025 | | Q2 | January - March | Q2 FY2026 = Jan-Mar 2026 | | Q3 | April - June | Q3 FY2026 = Apr-Jun 2026 | | Q4 | July - September | Q4 FY2026 = Jul-Sep 2026 |

Common Documentation Labels

• documentation-design.va.gov - General documentation issues
• va-[component] - Component-specific (e.g., va-alert, va-button)
• pattern - Pattern documentation
• accessibility - Accessibility-related documentation

File Path Patterns

| Content Type | Path Pattern | |--------------|--------------| | Components | src/_components/[name]/index.md or src/_components/[name].md | | Patterns | src/_patterns/[category]/[name].md (categories: ask-users-for, help-users-to) | | Templates | src/_templates/[name].md or src/_templates/[category]/index.md | | Foundation | src/_foundation/[topic].md (some use src/_foundation/[topic]/index.md) | | Content Guide | src/_content-style-guide/[topic].md |

Issue Management Commands

# Assign an issue to yourself
gh issue edit <NUMBER> --repo department-of-veterans-affairs/vets-design-system-documentation --add-assignee "<USERNAME>"

# View issue's project board status
gh issue view <NUMBER> --repo department-of-veterans-affairs/vets-design-system-documentation --json projectItems | cat

# Add a comment to an issue
gh issue comment <NUMBER> --repo department-of-veterans-affairs/vets-design-system-documentation --body "Working on this - PR coming soon"

Useful Commands

# List all documentation issues
gh issue list --repo department-of-veterans-affairs/vets-design-system-documentation --label "documentation-design.va.gov" --state open

# List unassigned documentation issues only
gh issue list --repo department-of-veterans-affairs/vets-design-system-documentation --label "documentation-design.va.gov" --state open --json number,title,assignees | cat | jq '[.[] | select(.assignees | length == 0)]'

# Search for issues mentioning a component
gh issue list --repo department-of-veterans-affairs/vets-design-system-documentation --search "va-alert in:title,body"

# View issue with comments
gh issue view <NUMBER> --repo department-of-veterans-affairs/vets-design-system-documentation --comments

# Check if file exists
ls src/_components/<component-name>/

# Search documentation content
grep -r "search term" src/_components/