Use Feature Backlog Sync¶

Overview¶

The feature-backlog-sync skill automatically synchronizes GitHub Issues and ZenHub tickets with the SyRF documentation framework, creating feature briefs and updating planning docs.

Note: This skill is defined in .claude/skills/feature-backlog-sync/SKILL.md (not committed to git, workspace-specific).

When to Use¶

Use this skill to:

Sync backlog with docs: Create feature briefs for undocumented issues
Update sprint docs: Sync sprint-current.md with ZenHub active sprint
Check documentation coverage: See what % of active issues have documentation
Generate feature briefs: Auto-create docs from GitHub issue content

Installation¶

The skill is already created in your Claude Code workspace. To verify:

ls .claude/skills/feature-backlog-sync/SKILL.md

If missing, ask Claude Code to recreate the skill from this documentation.

Usage¶

Basic Workflow¶

Step 1: Discovery (Read-Only Analysis)

Ask Claude Code:

@feature-backlog-sync: What issues are missing documentation?

This runs Mode 1: Discovery and reports:

Total active issues (In Progress + In Review + Ready for Dev)
Documentation coverage percentage
List of issues without feature briefs
Orphaned documentation (docs referencing closed issues)
Sprint sync status

Example output:

📊 Backlog Sync Analysis
========================

Active Issues: 23 total
  In Progress: 8 issues
  In Review: 7 issues
  Ready for Dev: 8 issues

Documentation Coverage:
  ✓ With documentation: 15 (65%)
  ✗ Missing documentation: 8 (35%)

Issues Missing Documentation:
  #456 - Implement advanced search filters (In Progress, @alice)
  #457 - Add bulk export functionality (In Progress, @bob)
  ...

Step 2: Generate Feature Briefs

Ask Claude Code:

@feature-backlog-sync: Create feature briefs for undocumented issues

This runs Mode 2: Feature Brief Generation and:

Fetches full details for each undocumented issue from GitHub
Parses issue body (problem, solution, acceptance criteria)
Generates properly formatted feature brief with YAML frontmatter
Writes to docs/features/[sanitized-title].md
Runs docs/scripts/generate-indexes.sh to update index
Reports created files

Example output:

✨ Created Feature Briefs
==========================

✓ docs/features/implement-advanced-search-filters.md (Issue #456)
✓ docs/features/add-bulk-export-functionality.md (Issue #457)
...

Documentation coverage improved: 65% → 100% 🎉

Step 3: Review and Enhance

Auto-generated feature briefs start with status: "Draft". Review and enhance:

# Review generated feature briefs
ls docs/features/*.md | grep -v index.md

# Edit to add technical details
vim docs/features/implement-advanced-search-filters.md

Update fields:

Add technical architecture notes
Link to related ADRs
Clarify acceptance criteria
Add dependencies and blockers
Change status to "In-Review" when ready

Step 4: Update Sprint Docs

Ask Claude Code:

@feature-backlog-sync: Update sprint documentation

This runs Mode 3: Sprint Documentation Update and:

Fetches active sprint from ZenHub
Updates docs/planning/migration/sprint-current.md
Updates docs/planning/migration/backlog.md
Updates docs/planning/migration/status.md
Reports changes

Step 5: Commit Changes

# Review changes
git status docs/features docs/planning

# Commit feature briefs
git add docs/features/*.md docs/*/index.md
git commit -m "docs: auto-generate feature briefs from GitHub issues"

# Commit planning updates
git add docs/planning/migration/*.md
git commit -m "docs: update sprint and backlog from ZenHub"

# Push
git push

Sync Modes¶

Mode 1: Discovery (Read-Only)¶

What it does: Analyzes active issues vs documentation without making changes

Use when:

Want to understand documentation gaps
Weekly documentation audits
Planning sprint retrospectives

Command:

@feature-backlog-sync: Run discovery mode

or

What issues are missing documentation?

Output: Analysis report with coverage metrics and gap list

Mode 2: Feature Brief Generation¶

What it does: Creates docs/features/*.md files from GitHub issues

Use when:

Starting new sprint (document all sprint issues)
Issue created without corresponding feature brief
Want to bulk-generate docs for backlog

Command:

@feature-backlog-sync: Create feature briefs for undocumented issues

or

Generate feature briefs for issues #456, #457, #458

Output: Created markdown files in docs/features/ with proper frontmatter

Generated frontmatter:

---
doc-type: "Feature"
status: "Draft"  # Always starts as Draft
author: "Auto-generated"
created: YYYY-MM-DD
updated: YYYY-MM-DD
zenhub-ticket: "#456"  # Links to source issue
tags: [extracted, from, issue, labels]
---

Mode 3: Sprint Documentation Update¶

What it does: Syncs docs/planning/migration/ files with ZenHub

Use when:

Sprint starts/ends
Want current sprint documentation
Backlog has changed significantly

Command:

@feature-backlog-sync: Update sprint documentation

or

Sync sprint docs with ZenHub

Output: Updated planning markdown files with current data

Feature Brief Structure¶

Auto-generated feature briefs follow this template:

---
doc-type: "Feature"
status: "Draft"
author: "Auto-generated"
created: 2025-11-24
updated: 2025-11-24
zenhub-ticket: "#456"
tags: [search, filters, ui, feature]
---

# Implement Advanced Search Filters

**Status**: In Progress
**Priority**: High
**Assignees**: @alice

## Problem Statement

Users need more granular search capabilities to filter systematic
reviews by multiple criteria simultaneously. Current search only
supports basic keyword matching.

## Proposed Solution

Add advanced filter panel with:
- Date range filtering
- Multiple tag selection
- Author filtering
- Status filtering

## Acceptance Criteria

- [ ] Filter panel UI implemented
- [ ] Filters apply correctly to search results
- [ ] Filters persist across sessions
- [ ] Unit tests for filter logic
- [ ] Integration tests for UI

## Technical Notes

**Architecture**:
- Frontend: Angular filter component
- Backend: Update search API to accept filter parameters
- Database: Add indexes for filtered fields

**Dependencies**:
- Requires API v2 endpoint migration (Issue #450)
- UI mockups pending (see Figma link)

## Related Issues

- Blocks: #460 (OAuth2 integration needs search)
- Related: #300 (Original search implementation)

---

**Source**: GitHub Issue #456
**Last Synced**: 2025-11-24 14:30

This feature brief was auto-generated from the GitHub issue.
Update with additional context as needed.

Best Practices¶

1. Run Discovery First¶

Always run Mode 1 (Discovery) before generating briefs:

User: "Sync backlog with docs"
→ Discovery analysis
→ Review gaps
→ Generate briefs for specific issues

This prevents:

Creating duplicate feature briefs
Generating briefs for closed/invalid issues
Missing orphaned documentation

2. Review Auto-Generated Content¶

Feature briefs are starting points, not final documentation:

After generation:

Read the auto-generated content
Add technical architecture details
Clarify ambiguous acceptance criteria
Link to related ADRs and docs
Update status from "Draft" to "In-Review"
Assign ownership (change author field)

Don't:

Commit auto-generated briefs without review
Assume issue description is complete
Skip adding technical context

3. Keep Frontmatter Updated¶

The zenhub-ticket field links docs to issues:

zenhub-ticket: "#456"  # Links to GitHub Issue #456

When to update:

Issue closed → Update status to "Completed"
Issue canceled → Update status to "Deprecated"
Issue moved to different epic → Update tags/references
Implementation merged → Add link to merged PR

4. Sync Regularly¶

Recommended cadence:

Daily: Mode 1 (Discovery) during standup
Sprint start: Mode 2 (Feature Brief Generation) for all sprint issues
Sprint end: Mode 3 (Sprint Documentation Update) for retrospective
Weekly: Full sync (all 3 modes) on Fridays

5. Archive Completed Features¶

When issues close, don't delete feature briefs:

# Move to completed subdirectory
mkdir -p docs/features/completed/
mv docs/features/implement-advanced-search-filters.md docs/features/completed/

# Or update status in place
# Change status: "Approved" → status: "Completed"

Completed features serve as implementation history and reference.

Troubleshooting¶

"Unknown skill: feature-backlog-sync"¶

Problem: Skill not recognized by Claude Code

Solution:

Check skill file exists:

ls .claude/skills/feature-backlog-sync/SKILL.md

If missing, ask Claude Code to recreate:

Create the feature-backlog-sync skill as documented in
docs/how-to/use-feature-backlog-sync.md

Restart Claude Code IDE/extension if needed

"Issue #XXX not found"¶

Problem: Doc references non-existent issue

Cause: Issue was deleted, or wrong issue number in frontmatter

Solution:

Verify issue exists on GitHub
Update zenhub-ticket field if wrong
Archive doc if issue permanently deleted

"Duplicate filename"¶

Problem: Two issues sanitize to same filename

Example:

Issue #456: "Add search filters"
Issue #789: "Add search filters" → Both become add-search-filters.md

Solution: Skill automatically appends issue number:

add-search-filters-456.md
add-search-filters-789.md

"Rate limit exceeded"¶

Problem: Too many GitHub/ZenHub API calls

Solution:

Run sync mode-by-mode (not all at once)
Add delays between issue fetches
Cache issue data locally during session
Use GitHub token with higher rate limits

"Invalid YAML frontmatter"¶

Problem: Existing doc has malformed frontmatter, sync fails

Solution:

# Validate all docs first
./docs/scripts/validate-docs.sh --verbose

# Fix validation errors
# Then run sync again

Manual Sync (Without Skill)¶

If the skill isn't available, manually sync using MCP tools:

1. Get Active Issues¶

# Get ZenHub workspace info
@mcp__zenhub__getWorkspacePipelinesAndRepositories

# Get issues in "In Progress" pipeline
@mcp__zenhub__getIssuesInPipeline
# Provide: pipelineId, repositoryIds

# Get active sprint
@mcp__zenhub__getActiveSprint

2. List Existing Docs¶

# Find feature briefs
ls docs/features/*.md

# Extract zenhub-ticket references
grep -r "zenhub-ticket:" docs/features docs/planning

3. Compare and Identify Gaps¶

Manually compare issue numbers from ZenHub with zenhub-ticket fields in docs.

4. Create Feature Brief Manually¶

Use the Q&A template as a starting point:

cp docs/planning/templates/qa-template.md docs/features/new-feature.md
# Edit with issue details

Or use the feature brief template structure shown above.

Metrics and Reporting¶

Documentation Coverage¶

Calculate coverage percentage:

Coverage = (Issues with docs / Total active issues) × 100%

Example:

Active issues: 23
With documentation: 15
Coverage: 15/23 = 65%

Target: 80%+ coverage for active sprint issues

Sprint Documentation Health¶

Check sprint doc freshness:

# When was sprint doc last updated?
ls -l docs/planning/migration/sprint-current.md

# Compare with sprint dates
# If > 3 days old → Run Mode 3 sync

Orphaned Documentation¶

Count docs referencing closed issues:

# Find all zenhub-ticket references
grep -r "zenhub-ticket:" docs/features --include="*.md"

# Cross-reference with closed issues
# Mark for archival or status update

Integration with Existing Workflow¶

With Feature Planning Workflow¶

Product Owner creates GitHub Issue with:
Problem statement
Proposed solution
Acceptance criteria
Run feature-backlog-sync (Mode 2)
Auto-generates feature brief from issue
Team enhances feature brief:
Add technical details (see Feature Planning Workflow)
Use Q&A iteration if needed
Create technical plan
Link to ADRs
Implementation and tracking:
Update status as work progresses
Sync sprint docs (Mode 3) weekly
Mark completed when merged

With Q&A Iteration Process¶

Combine auto-generation with Q&A refinement:

Auto-generate initial feature brief (Mode 2)
Use Q&A template for refinement:

cp docs/planning/templates/qa-template.md docs/planning/feature-name-qa.md

Iterate on technical details (Iteration 1-3)
Update feature brief with Q&A insights
Create ADRs for key decisions
Delete Q&A file after incorporation

With CI/CD Workflow¶

Auto-sync can trigger on GitHub webhook:

# .github/workflows/docs-sync.yml (future)
on:
  issues:
    types: [opened, labeled]
  schedule:
    - cron: '0 9 * * 1'  # Monday 9 AM

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Run feature-backlog-sync
        # Invoke skill via CI
        # Create PR with generated briefs

Documentation Framework Guide - YAML frontmatter standards
Feature Planning Workflow - Manual feature planning process
Q&A Template - Iterative refinement
CI/CD Workflow Overview - Pipeline integration

Skill Definition Location¶

The skill is defined in .claude/skills/feature-backlog-sync/SKILL.md (gitignored, workspace-specific).

To recreate the skill in a new workspace, refer to the comprehensive skill definition which includes:

3 sync modes (Discovery, Feature Brief Generation, Sprint Update)
Issue parsing strategies
Filename sanitization rules
YAML frontmatter templates
Error handling patterns
MCP tool integration
Example conversations

Allowed Tools: Read, Write, Edit, Glob, Grep, GitHub MCP, ZenHub MCP

Use Feature Backlog Sync¶

Overview¶

When to Use¶

Installation¶

Usage¶

Basic Workflow¶

Sync Modes¶

Mode 1: Discovery (Read-Only)¶

Mode 2: Feature Brief Generation¶

Mode 3: Sprint Documentation Update¶

Feature Brief Structure¶

Best Practices¶

1. Run Discovery First¶

2. Review Auto-Generated Content¶

3. Keep Frontmatter Updated¶

4. Sync Regularly¶

5. Archive Completed Features¶

Troubleshooting¶

"Unknown skill: feature-backlog-sync"¶

"Issue #XXX not found"¶

"Duplicate filename"¶

"Rate limit exceeded"¶

"Invalid YAML frontmatter"¶

Manual Sync (Without Skill)¶

1. Get Active Issues¶

2. List Existing Docs¶

3. Compare and Identify Gaps¶

4. Create Feature Brief Manually¶

Metrics and Reporting¶

Documentation Coverage¶

Sprint Documentation Health¶

Orphaned Documentation¶

Integration with Existing Workflow¶

With Feature Planning Workflow¶

With Q&A Iteration Process¶

With CI/CD Workflow¶

Related Documentation¶

Skill Definition Location¶