Jira Agentic Requirements Pipeline

Jira Agentic Requirements Pipeline

Execute this workflow to convert ambiguous Jira tickets into actionable engineering inputs without inventing product decisions.

Quick start

export JIRA_BASE_URL="https://example.atlassian.net"
export JIRA_EMAIL="you@example.com"
export JIRA_API_TOKEN="<your-jira-api-token>"

CLI=jira-agentic-requirements-pipeline/scripts/jira_pipeline_cli.py

python3 "$CLI" fetch-issue DEMO-1 --output issue.json
python3 "$CLI" discovery --input issue.json --output analysis.json
python3 "$CLI" generate-questions --input analysis.json --output questions.json
python3 "$CLI" collect-input --input questions.json --state-file .jira_requirement_state.json
python3 "$CLI" resolve-contract --questions questions.json --answers .jira_requirement_state.json --output contract.json
python3 "$CLI" base-branch-plan --analysis analysis.json --contract contract.json --output plan.json

Output files at each step:

Mandatory flow (run in order)

1. Fetch Jira issue with scripts/jira_pipeline_cli.py fetch-issue.
2. Run requirement discovery with scripts/jira_pipeline_cli.py discovery.
3. Generate business questions with scripts/jira_pipeline_cli.py generate-questions.
4. Collect business answers in terminal with scripts/jira_pipeline_cli.py collect-input.
5. Resolve functional contract with scripts/jira_pipeline_cli.py resolve-contract.
6. Build base-branch plan with scripts/jira_pipeline_cli.py base-branch-plan.

If required answers are missing, stop in phase 1 and do not plan implementation.

Decision rules

• Ask only functional/product/operations questions.
• Infer architecture and implementation details from repository patterns.
• Keep required questions small and prioritized (typically 5-10 per ticket).
• The selector reserves a baseline budget (default 4) for universally required P0 templates (objective / scope / rules / lifecycle) and a signal budget (default 6) for templates whose declared signals match the ticket's missing decisions. Tune via --baseline-budget and --signal-budget.
• If inference confidence is low (< 0.65), generate questions only and request human review.
• Never auto-merge.

Jira integration

Set environment variables:

• JIRA_BASE_URL (example: https://company.atlassian.net, no trailing slash needed)
• JIRA_EMAIL
• JIRA_API_TOKEN

The CLI uses Jira REST API v3 and pages through the /comment endpoint until every comment is fetched. Cap with --max-comments (default 1000); a stderr warning fires if the cap clipped the result.

Three modes: rules, llm-augmented, hybrid

The pipeline keeps a deterministic rule-based core (free, offline, reproducible) and lets the host model that invokes this skill augment it. The skill never calls a model itself — the model executing the skill is the one in your editor (Claude in Cursor, Claude Projects, ChatGPT, Gemini, etc.). Three modes:

1. rules (default, no model required)

Run the six commands above. The rule-based inferencers in scripts/jira_pipeline_cli.py produce every artifact deterministically from keyword and density signals.

2. llm-augmented

After discovery the host model reads analysis.json and emits a refinement patch as JSON. Allowed keys are exactly:

businessGoal, functionalEntities, userActions, possibleAffectedFlows,
explicitRequirements, missingBusinessDecisions, detectedCategories,
ambiguityLevel

Anything else is rejected. Save the patch (e.g. suggestions.json) and merge it:

python3 "$CLI" merge-llm-suggestions \
  --analysis analysis.json \
  --suggestions suggestions.json

The merger:

• unions list-shaped fields with the rule-based output (so additions compound, deterministic core is never overwritten);
• replaces scalar fields and keeps the original under _llmAugmentation.ruleBasedSnapshot.<field> for provenance;
• records every accepted/rejected key under _llmAugmentation.

The output stays usable by generate-questions and base-branch-plan without changes — both continue to consume analysis.json.

3. hybrid

Hybrid is just the orchestration: run discovery first, hand analysis.json to the host model with the prompt in templates/llm-augmentation-prompt.md, merge the patch, then continue with the rest of the pipeline. The deterministic baseline is always present; the model only refines.

CLI mode without losing session state

For business input in terminal:

• Run collect-input with --state-file.
• State is persisted after each answer.
• If terminal closes or receives Ctrl+C, rerun and continue from the next pending question.
• Use --non-interactive to validate required completeness in CI or automation.

Artifact contracts

Every artifact emitted by the CLI carries a top-level schemaVersion (currently 1.0.0). See references/contracts.md for the full shape and docs/contracts.md for the repo-wide versioning policy.

References, examples, and troubleshooting

• Internal contracts: references/contracts.md
• Full business question catalog and prioritization: references/question-catalog.md
• Worked examples (three end-to-end runs): EXAMPLES.md
• Common problems and fixes: TROUBLESHOOTING.md
• Jira/report templates: templates/

Guardrails

• Phase 1 is read-only for code changes.
• Phase 2 can prepare a base branch plan/report but must not merge.
• Keep mandatory traceability: ticket -> questions -> answers -> functional contract -> implementation plan.