Add jira-refiner agent to enrich sparse tickets before docs-orchestrator runs. Block docs-orchestrator on malformed Jira input

[mcljot]

Problem

Users invoke docs-orchestrator with JIRA tickets that lack the context needed to produce useful documentation. Common scenarios:

• Sparse ticket: Empty or one-line description, no acceptance criteria, no affected components listed
• No supporting links: No linked PRs, no upstream issues, no design docs or Google Docs referenced in the ticket
• No source code repo: Neither --source-code-repo nor --pr supplied, and the ticket itself has no git links in comments or web links
• No associated PR: The feature code has landed but nobody linked the PR to the ticket

Today, the orchestrator has no pre-flight validation for ticket quality. The docs-workflow-jira-ready skill only checks whether a progress file already exists — it doesn't inspect ticket content. The requirements-analyst agent receives the sparse ticket, does its best with web search to fill gaps, and produces a thin requirements.md that leads to low-quality documentation downstream.

The result is wasted compute, wasted reviewer time, and docs that need to be substantially rewritten or abandoned. The failure mode is silent — the orchestrator completes successfully but produces garbage.

Proposed solution

1. New jira-refiner agent

Add a jira-refiner agent (in docs-tools) that runs before the requirements step and attempts to automatically enrich the JIRA ticket with missing context. It should do things like:

• Fetch the ticket graph via jira-reader --graph TICKET --fetch-details to pull in parent, children, sibling, and linked issue context
• Search for associated PRs/MRs by querying GitHub/GitLab for the ticket ID in commit messages, branch names, and PR titles (e.g., gh search prs PROJ-123)
• Discover the source code repo from any PRs found, from git links in JIRA comments, or from project-level conventions
• Follow web links in the ticket (Google Docs, Confluence pages, design docs) and extract relevant context
• Write enrichment back to JIRA via jira-writer — add discovered PRs as web links, update the description with structured context, add a comment summarizing what was found or create a new section in the ticket Description field aimed at agent ingestion

The agent should be idempotent — running it twice on the same ticket shouldn't duplicate links or comments.

2. Readiness gate with minimum-quality criteria

After the refiner runs, evaluate the enriched ticket against a minimum-quality checklist:

Criterion	Required?	How to check
Description is non-empty and >50 characters	Yes	JIRA field inspection
At least one linked PR or source code repo available	Yes	JIRA git links, web links, or --pr/--source-code-repo args
Summary is descriptive (not just a ticket type prefix)	Yes	Heuristic check
At least one of: acceptance criteria, affected component, or fix version	Recommended	JIRA field inspection

If the ticket fails required criteria after enrichment, the orchestrator should fail immediately with a clear error message telling the user what's missing and what they need to add manually. Example:

ERROR: JIRA ticket PROJ-123 does not meet minimum quality for documentation generation.

After automated enrichment, the following are still missing:
✗ No linked PRs or source code repository found
✗ Description is empty

The jira-refiner agent searched for PRs matching "PROJ-123" and found none.

Action required:

1. Link the relevant PR(s) to the JIRA ticket
2. Add a description explaining what changed and why
3. Re-run: docs-orchestrator PROJ-123

3. Integration with docs-orchestrator

Add a new workflow step that runs before requirements:

steps:                                                                   
  - name: refine-ticket
    skill: docs-tools:jira-refiner                                                                                                                                                 
    description: Enrich sparse JIRA ticket with discovered context
  - name: requirements                                                                                                                                                             
    skill: docs-tools:docs-workflow-requirements                         
    inputs_from: [refine-ticket]                                                                                                                                                   
    # ... existing config