From sdd
Retroactively adds Branch and PR Convention sections to existing spec-related issues using templates from references/issue-authoring.md and configs from CLAUDE.md. Useful for enriching legacy issues with workflow standards.
npx claudepluginhub joestump/claude-plugin-sdd --plugin sddThis skill uses the workspace's default tool permissions.
<!-- Governing: ADR-0015 (Markdown-Native Configuration), SPEC-0014 REQ "Config Resolution Pattern" -->
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Guides code writing, review, and refactoring with Karpathy-inspired rules to avoid overcomplication, ensure simplicity, surgical changes, and verifiable success criteria.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Share bugs, ideas, or general feedback.
You are retroactively adding ### Branch and ### PR Convention sections to existing tracker issues that were created by /sdd:plan (or manually) for a given spec. The canonical templates for these sections live in references/issue-authoring.md § Enrichment Sections (which references shared-patterns.md for the underlying Branch Naming Conventions and PR Close Keywords). This skill is purely additive — it never replaces existing content.
Resolve artifact paths: Follow the Artifact Path Resolution pattern from references/shared-patterns.md to determine the spec directory. If $ARGUMENTS contains --module <name>, resolve paths relative to that module. The resolved spec directory is {spec-dir}.
Parse arguments: Extract from $ARGUMENTS:
SPEC-0007) or capability directory name--branch-prefix <prefix>: Custom branch prefix instead of the default prefixes. Default: feature.--dry-run: Preview what would be added without modifying any issues. Default: off.--module <name>: Resolve artifact paths relative to the named module. Default: none.If no spec identifier is provided, list available specs by globbing {spec-dir}/*/spec.md, read the title from each, and use AskUserQuestion to ask which spec to enrich.
Resolve spec: Follow the plugin's references/shared-patterns.md § "Spec Resolution" (which uses {spec-dir} from the Artifact Path Resolution pattern).
Read spec: Read {spec-dir}/{capability-name}/spec.md to get the spec number and understand the requirements. Validate spec pairing per references/shared-patterns.md § "Spec Pairing Validation".
Detect tracker: Follow the "Tracker Detection" flow in the plugin's references/shared-patterns.md. If no tracker is found, error — enrichment requires a tracker.
Read branch/PR config from CLAUDE.md: Follow the "Config Resolution" pattern in the plugin's references/shared-patterns.md. Read the ### SDD Configuration section from CLAUDE.md, specifically the #### Branch Conventions and #### PR Conventions subsections:
#### Branch Conventions
- **Enabled**: true
- **Prefix**: feature
- **Epic Prefix**: epic
- **Slug Max Length**: 50
#### PR Conventions
- **Enabled**: true
- **Close Keyword**: Closes
- **Ref Keyword**: Part of
- **Include Spec Reference**: true
Enabled under Branch Conventions is false, skip ### Branch sections entirelyEnabled under PR Conventions is false, skip ### PR Convention sections entirelyPrefix from Branch Conventions as the default task prefix (overridden by --branch-prefix)Epic Prefix from Branch Conventions for epic issues (default: epic)Slug Max Length from Branch Conventions for slug truncation (default: 50)Close Keyword from PR Conventions if set; otherwise use tracker-specific defaultsRef Keyword from PR Conventions for epic/spec references (default: "Part of")Find existing issues: Search the tracker for issues referencing the spec number.
gh issue list --search "SPEC-XXXX" --json number,title,body,labels --limit 100ToolSearch)glab issue list --search "SPEC-XXXX"bd list or similar to find tasks referencing the specFor each issue:
a. Read the current issue body (via tracker API or CLI).
b. Check if a ### Branch section already exists in the body. If yes, skip adding it (idempotent).
c. Check if a ### PR Convention section already exists in the body. If yes, skip adding it (idempotent).
d. Determine the slug from the issue title:
Slug Max Length from CLAUDE.md Branch Conventions)e. Determine if the issue is an epic:
epic label → epicf. If ### Branch section is missing and branches.enabled is not false, append:
### Branch
`{prefix}/{issue-number}-{slug}`
Where {prefix} is:
epic (or CLAUDE.md Branch Conventions > Epic Prefix or --branch-prefix)feature (or CLAUDE.md Branch Conventions > Prefix or --branch-prefix)g. If ### PR Convention section is missing and pr_conventions.enabled is not false, append:
### PR Convention
{close-keyword} #{issue-number}
{ref-keyword} #{epic-number} (SPEC-XXXX)
Tracker-specific close keywords: see the plugin's references/shared-patterns.md § "PR Close Keywords".
h. Auto-create labels (Governing: SPEC-0011 REQ "Auto-Create Labels"): When applying labels like epic or story during enrichment, use the try-then-create pattern (see references/shared-patterns.md § "Try-Then-Create Label Pattern").
i. Update the issue body with the appended sections using the tracker API or CLI.
--dry-run mode: If --dry-run is set, show what sections would be added to which issues but don't modify anything:
Report results: Provide a summary:
### Branch, how many got ### PR ConventionBefore iterating issues, sync the {repo}-issues qmd collection from the tracker so the local cache reflects current issue state. This is Tier 4 of the freshness model: always sync at consumer entry, subject to a 5-minute deduplication window.
.sdd/issues/_meta.json (per references/tracker-sync.md § "Cursor Management"). If last_sync is within the last 5 minutes, skip the sync and proceed silently.references/tracker-sync.md § "Per-Tracker Sync" with the cursor.{tracker} from _meta.json for incremental fetch. Print a one-line note: "Syncing N issues from {tracker}…".references/tracker-sync.md § "Failure Modes and Degradation" — emit a one-line warning and proceed with live tracker queries (the pre-v5 path) for this run. Do NOT block; enrichment is the user's primary intent.After all issue body updates complete (step 7.i), trigger a narrow re-sync of the {repo}-issues collection so the qmd index reflects the appended ### Branch and ### PR Convention sections. Use the canonical update pattern from references/qmd-helpers.md § "Update Patterns" → "Narrow update".
qmd update per the qmd-helpers pattern.{repo}-issues — run /sdd:index update manually") but report the enrichment itself as successful.This skill reads the Branch Conventions and PR Conventions subsections of the ### SDD Configuration section in CLAUDE.md. See the plugin's references/shared-patterns.md § "Config Resolution" for the canonical format and defaults, and § "Branch Naming Conventions" and "PR Close Keywords" for conventions.
### Branch or ### PR Convention sections (idempotent)ToolSearch for tracker tools at runtimereferences/shared-patterns.md to read configuration from CLAUDE.mdreferences/shared-patterns.md) for all label applications — never fail on missing labels (Governing: SPEC-0011 REQ "Auto-Create Labels")--review support (utility skill).sdd/issues/ before iterating issues, subject to the 5-minute dedup window. On sync failure, fall back to live tracker queries with a one-line warning (NEVER block) (Governing: ADR-0026, SPEC-0019 REQ "Tier 4 Always-Sync Issues for Sprint Skills"){repo}-issues after enrichment per Step 10 — best-effort, silent on success, one-line warning on failure (Governing: ADR-0026, SPEC-0019 REQ "Tier 1 Mutation-Aware Updates")