Ready To Solve

Name

jira:ready-to-solve

Synopsis

/jira:ready-to-solve <jira-issue-key> [--dry-run] [--verbose] [--fix]

Description

The jira:ready-to-solve command checks whether a Jira issue has sufficient grooming for /jira:solve to produce a quality solution.

It runs a two-phase validation:

1. Deterministic checks via a Python script that verifies structural requirements: required sections exist, are non-empty, and have adequate content.
2. AI qualitative assessment that evaluates whether the acceptance criteria are specific and testable, whether there is enough implementation context, and whether clear success/failure conditions exist.

On pass, the label ready-to-solve is added to the issue. On fail, not-ready-to-solve is added. The stale opposite label is removed if present.

With --fix, when validation fails the command generates a revised description that adds or improves the failing sections, shows the proposed changes to the user for approval, and updates the Jira issue description upon confirmation.

Prerequisites

• Jira MCP server configured (Atlassian Rovo MCP)
• Python 3.8+ (which python3)

Implementation

Phase 1: Fetch Issue Data

Fetch the issue via getJiraIssue with the issue key.

Extract from the response:

• fields.description -- full description text
• fields.summary -- issue title
• fields.labels -- current labels array (needed for label updates)
• fields.status.name -- current status
• fields.issuetype.name -- issue type

If description is null or empty, skip to Phase 4 with an automatic FAIL verdict.

Phase 2: Run Deterministic Checks

Pipe the description to the Python script:

echo '{"description": "<description_content>"}' | python3 plugins/jira/skills/ready-to-solve/scripts/check_sections.py

For verbose output (includes matched content):

echo '{"description": "<description_content>"}' | python3 plugins/jira/skills/ready-to-solve/scripts/check_sections.py --verbose

Important: Construct the JSON input carefully. The description may contain quotes, newlines, and special characters. Use Python or jq to safely serialize:

echo "$DESCRIPTION" | jq -Rs '{"description": .}' | python3 plugins/jira/skills/ready-to-solve/scripts/check_sections.py

The script outputs JSON with per-check results. Parse the output to get:

• overall_pass: boolean -- whether all REQUIRED checks passed
• checks: array of individual check results
• stats: summary counts

Deterministic checks performed by the script:

Note: WARNING checks are reported but do not block the overall verdict. Only REQUIRED checks must pass for the issue to be considered ready.

Phase 3: AI Qualitative Assessment

Read the full description and evaluate three dimensions. For each, produce a verdict (PASS or FAIL) and a 1-2 sentence justification.

1. AC Specificity and Testability: Are acceptance criteria specific enough to write tests against? Do they describe observable behavior rather than vague goals?

   • FAIL: no acceptance criteria, or criteria are vague ("it should work", "system performs well")
   • PASS: criteria describe observable behavior ("when X happens, Y returns Z", "API returns 404 for missing resources")

2. Implementation Context Sufficiency: Is there enough description of the problem, affected code area, or desired behavior that /jira:solve could identify relevant files and implement a solution?

   • FAIL: a codebase search would be ambiguous (no component, file, or feature area mentioned)
   • PASS: the description points to a specific area of the codebase, component, or behavior

3. Clear Success/Failure Conditions: Can a reviewer determine whether a proposed solution addresses the issue?

   • FAIL: no way to tell if a solution is correct (no expected behavior, no test criteria)
   • PASS: conditions are explicit enough to verify a solution

Phase 4: Aggregate Verdict

overall_pass = (all REQUIRED deterministic checks pass) AND (no AI check has verdict FAIL)

Collect all failures and warnings into a list for the report.

Phase 5: Fix Failing Checks (if --fix)

Skip if --fix is not set or if validation already passed.

When validation fails and --fix is set, generate a revised description that fixes the failing checks:

1. Identify failures: Collect all failed deterministic checks and AI qualitative FAILs from phases 2-4.

2. Generate revised description: Preserve ALL existing content from the original description. Only add or expand sections -- never remove or rewrite content the user wrote. For each failure:

   • Missing Context/Why section: Generate an h2. Why section from the issue summary and any context in the existing description text.
   • Missing Acceptance Criteria: Generate an h2. Acceptance Criteria section with concrete, testable bullet points derived from the description context.
   • Missing Technical Details: Generate an h2. Technical Details section from any code references, file paths, component mentions, or technical context in the description.
   • Section too short: Expand the existing section with additional relevant detail while preserving the original content.
   • AC lacks list items: Restructure the existing AC text into proper bullet points and add additional criteria if needed.
   • Vague acceptance criteria: Rewrite vague criteria to be specific and testable (e.g., "works" becomes "returns 200 on valid input").
   • Insufficient implementation context: Add implementation pointers -- component names, likely file paths, related features.
   • Unclear success conditions: Add explicit done criteria and edge cases.

3. Present proposed changes to the user: Show the full proposed description, clearly indicating what was added or changed (e.g., mark new sections with a note). Ask the user: "Here is the proposed updated description. Apply this to the Jira issue? (yes/no)"

4. If confirmed: Update the issue description via editJiraIssue, setting the description field to the revised text with contentFormat: "markdown".

5. Re-run validation: After updating, re-run phases 2-4 on the new description to confirm the issue now passes. Report the re-validation results.

6. If declined: Skip the update and proceed to label application and reporting with the original validation result.