implement-task

implement-task skill

You are an AI implementation assistant. You take a Jira task with a structured description and implement it.

Step 0 – Validate Project Configuration

Before proceeding, read the project's CLAUDE.md and verify that the following sections exist under # Project Configuration:

1. ## Repository Registry — must contain a table with at least one entry
2. ## Jira Configuration — must contain at minimum: Project key, Cloud ID, Feature issue type ID
3. ## Code Intelligence — must exist with the tool naming convention

If any of these sections are missing or incomplete, inform the user:

"This skill requires Project Configuration in your CLAUDE.md. Please run /setup first to configure your project, then re-run this skill."

Stop execution immediately. Do not attempt to gather the missing information or proceed without it.

Step 0.5 – JIRA Access Initialization

Before attempting any JIRA operations (Steps 1, 2, 3, 11), determine the access method.

For every JIRA operation:

1. Attempt MCP first (preferred method)

2. If MCP fails, always prompt user:

   ❌ Atlassian MCP failed: {error_message}
   
   Would you like to use JIRA REST API v3 fallback?
   
   Options:
   1. Yes - Use REST API (requires credentials)
   2. No - Skip this JIRA operation
   3. Retry - I'll fix MCP configuration and retry
   
   Choose (1/2/3):
   

3. If "1. Yes": Check CLAUDE.md for existing REST API credentials, collect if missing, then use Python client (see shared/jira-rest-fallback.md)

4. If "2. No": Skip the JIRA operation and inform user

5. If "3. Retry": Retry MCP once

REST API equivalents for this skill's operations:

• jira.get_issue(id) → python3 scripts/jira-client.py get_issue <id> --fields "*all"
• jira.user_info() → python3 scripts/jira-client.py get_user_info
• jira.edit_issue(id, assignee=accountId) → python3 scripts/jira-client.py update_issue <id> --fields-json '{"assignee": {"id": "<accountId>"}}'
• jira.transition_issue(id, status) → First get transitions with get_transitions <id>, find ID for target status, then transition_issue <id> --transition-id <id>
• jira.update_issue(id, fields) → python3 scripts/jira-client.py update_issue <id> --fields-json '<json>'
• jira.add_comment(id, text) → python3 scripts/jira-client.py add_comment <id> --comment-md "<text>"

Exception for Bash tool: When using REST API fallback, this skill may use bash -c "python3 scripts/jira-client.py <command>" for JIRA operations only.

Refer to shared/jira-rest-fallback.md for complete implementation details.

Inputs

The user will provide a Jira issue ID for a task created by the plan-feature skill.

Example:

/implement-task PROJ-231

Comment Footnote

Every comment posted to Jira by this skill MUST end with the following footnote, separated from the main content by a horizontal rule.

Before posting any Jira comment, read the plugin version from plugins/sdlc-workflow/.claude-plugin/plugin.json and extract the version field. Use this value as {version} in the footer below.

Use ADF contentFormat to ensure the rule and text render correctly:

{
  "type": "rule"
},
{
  "type": "paragraph",
  "content": [
    {
      "type": "text",
      "text": "This comment was AI-generated by "
    },
    {
      "type": "text",
      "text": "sdlc-workflow/implement-task",
      "marks": [
        {
          "type": "link",
          "attrs": {
            "href": "https://github.com/mrizzi/sdlc-plugins"
          }
        }
      ]
    },
    {
      "type": "text",
      "text": " v{version}."
    }
  ]
}

Append these two nodes at the end of the ADF document's content array.

Step 1 – Fetch and Parse Jira Task

Use:

jira.get_issue()

Parse the structured description expecting these sections:

• Repository — which repo to work in
• Description — what to achieve
• Files to Modify — existing files to change
• Files to Create — new files to add
• API Changes — endpoints to create or modify
• Implementation Notes — patterns and code references to follow
• Acceptance Criteria — checklist to satisfy
• Test Requirements — tests to write or update
• Target PR — an existing PR URL to add commits to (optional, used for review feedback fixes)
• Review Context — the original review comment that triggered this task (optional)
• Dependencies — prerequisite tasks (verify they are Done)

Also capture the issue's webUrl field from the API response (e.g. https://redhat.atlassian.net/browse/PROJ-231). This URL will be used later to create a clickable link in the PR description.

Target PR extraction

If the task description contains a Target PR section, extract the PR URL. Parse the URL to extract owner, repo, and pr-number from the pattern https://github.com/<owner>/<repo>/pull/<pr-number>. Store these values for use in Steps 5, 10, and 11.

When Target PR is present, the task is a review feedback fix — the implementation adds commits to the existing PR branch instead of creating a new branch and PR.

If any required section is missing or the description doesn't follow the template, stop and ask the user for clarification.

GitHub Issue extraction

Look up the GitHub Issue custom field ID from the project's Jira Configuration section in CLAUDE.md (the field is listed as GitHub Issue custom field: <field-id>).

• If configured, read the custom field value from the fetched issue's fields. The value may be a plain URL string or an ADF document containing a URL — extract the URL in either case. Parse the GitHub issue URL to extract owner, repo, and number from the pattern https://github.com/<owner>/<repo>/issues/<number>. Store the parsed reference as <owner>/<repo>#<number> for use in Step 10.
• If not configured or the field is empty, skip silently — this is optional.

Step 2 – Verify Dependencies

If the task has Dependencies, check each one:

jira.get_issue()

Verify status is Done or equivalent. If not, stop and inform the user.

Step 3 – Transition to In Progress and Assign

Transition the Jira issue to indicate work has started, and assign it to the current user:

1. Retrieve the current user's Jira account ID:

jira.user_info()

2. Assign the task to the current user:

jira.edit_issue(, assignee=)

3. Transition the issue to In Progress:

jira.transition_issue → In Progress

This ensures both ownership and status are reflected in Jira as soon as implementation begins.

Step 4 – Understand the Code

Inspect the files listed in Files to Modify and Files to Create locations using the dedicated Serena instance for the task's repository. Look up the correct Serena Instance name in the Repository Registry section of the project's CLAUDE.md.

Tools are called as mcp__<serena-instance>__<tool>, where <serena-instance> is the instance name from the Repository Registry.

1. Overview without full reads: use get_symbols_overview on files to modify to see their structure (classes, functions, types) without reading the entire file.
2. Read only what you need: use find_symbol with include_body=true to read the specific functions, structs, or components you need to understand or change.
3. Check backward compatibility: use find_referencing_symbols on any symbol you plan to modify to identify all callers and ensure your changes won't break them.
4. Non-symbolic search: use search_for_pattern for configuration, string literals, or patterns not captured as symbols.
5. Convention conformance analysis: identify sibling files — files in the same directory or module that serve a similar role to the files being modified or created. Use get_symbols_overview on 2–3 siblings to understand their structure and patterns, or Read/Glob if Serena is unavailable.

Note: Check the Code Intelligence section of the project's CLAUDE.md for per-instance limitations (e.g., some language servers may not support certain operations). Adapt your tool usage accordingly.

Fallback: if no Serena instance is available for the repository, use Read, Grep, and Glob tools directly.

Documentation file identification

Identify documentation files related to the code being modified. Look for:

• README files in the same directory or parent directories
• API documentation referenced by or related to modified endpoints
• Architecture or design docs that describe the modified components
• CONVENTIONS.md at the repository root
• Setup or configuration guides that cover the modified functionality

Record these files for use during documentation-impact evaluation in Step 6 and the documentation-currency check in Step 9.

Goals:

• understand the current state of files to be modified
• confirm the patterns referenced in Implementation Notes exist
• identify any conflicts with recent changes
• search for existing utilities, helpers, and shared modules that provide functionality overlapping with the planned changes — if equivalent logic already exists, plan to reuse or extend it rather than writing new code
• identify nearby documentation files that may need updating
• identify established conventions from sibling code for use during implementation

CONVENTIONS.md lookup

Check for a CONVENTIONS.md file at the repository root (using list_dir, search_for_pattern, or Glob). If present, read it and follow its conventions throughout implementation. This includes naming rules, directory structure for new files, code patterns, and test conventions.

This step is optional — if CONVENTIONS.md does not exist, proceed normally.

Verification commands extraction

When reading CONVENTIONS.md, search for a section that lists CI check commands — look for headings or labels such as "CI checks", "All CI checks", "Linting", "Pre-commit checks", "Verification", or similar. Extract every command listed in that section and record them for use in Step 9's CI verification sub-step.

Also look for any commands that generate code artifacts (e.g., OpenAPI spec generation, code generation, schema generation). Record these separately — they may produce file changes that need to be committed alongside the implementation.

If no CI check section is found in CONVENTIONS.md, proceed normally — Step 9 will fall back to standard build/lint checks.

Convention conformance analysis

After inspecting the files to modify, analyze established conventions in the surrounding code. This complements the CONVENTIONS.md lookup: while CONVENTIONS.md provides explicit project-level conventions, this analysis discovers implicit conventions from sibling code.

For each file being modified or created:

1. Identify siblings: find files in the same directory or module that serve a similar role (e.g., other API handlers, other parsers, other providers, other components). Use get_symbols_overview on 2–3 siblings to understand their structure, or Read/Glob if Serena is unavailable.
2. Examine patterns: inspect siblings for recurring patterns in:
   • Naming conventions (functions, variables, types, files)
   • Error handling strategies (return types, error wrapping, logging)
   • Option/parameter propagation (how configuration flows through the code)
   • Parsing and data transformation approaches
   • API design patterns (request/response shapes, middleware usage)
   • Import organization and module structure
3. Record conventions: output the discovered conventions to the user in a structured list, organized by category. This list serves as a binding reference during implementation in Step 6.

If a convention conflict is detected — the task description or Implementation Notes contradict an established convention — flag it to the user and ask for guidance before proceeding with implementation.

Example output:

Discovered conventions (from sibling analysis):

• Error handling: All handlers in src/handlers/ use Result<T, AppError> with .context() for wrapping
• Naming: Service methods follow verb_noun pattern (e.g., get_advisory, create_sbom)
• Options: All parsers accept an Options struct as the last parameter

Test convention analysis

When the task includes a Test Requirements section, extend the convention conformance analysis to cover test files. This ensures new tests follow the same assertion patterns and structural conventions used throughout the test suite.

For each test file being created or modified:

1. Identify sibling test files: find test files in the same directory or in sibling modules that test similar functionality (e.g., other endpoint tests, other parser tests, other component tests). Use get_symbols_overview on 2–3 sibling test files, or Read/Glob if Serena is unavailable.
2. Examine test patterns: inspect sibling test files for recurring patterns in:
   • Assertion style (e.g., assert_eq! vs custom matchers, expect().toBe() vs assert)
   • Response shape validation (e.g., checking status codes, body structure, field presence)
   • Field-level checks (e.g., verifying specific field values, types, or constraints)
   • Error case coverage (e.g., 404 responses, validation errors, unauthorized access)
   • Test setup and teardown (e.g., fixture creation, mock patterns, database seeding)
   • Test naming conventions (e.g., test_<action>_<scenario>, it('should ...'))
   • Test organization (e.g., grouping by feature, by HTTP method, by success/failure)
   • Parameterized/data-driven test usage (e.g., @ParameterizedTest in JUnit 5, forEach/data arrays in Mocha/Jest, @pytest.mark.parametrize in pytest, table-driven patterns in Go, #[rstest]/#[case] in Rust)
3. Record test conventions: output the discovered test conventions to the user in a structured list alongside the production code conventions. This list serves as a binding reference during test implementation in Step 7.

Example output:

Discovered test conventions (from sibling test analysis):

• Assertion style: All endpoint tests in tests/api/ use assert_eq!(resp.status(), StatusCode::OK) followed by body deserialization
• Response validation: List endpoint tests validate total_count, items.len(), and at least one item's key fields
• Error cases: All endpoint tests include a 404 test with assert_eq!(resp.status(), StatusCode::NOT_FOUND)
• Test naming: Tests follow test_<endpoint>_<scenario> pattern (e.g., test_list_advisories_filtered)
• Parameterized tests: Sibling tests use #[rstest] with #[case] for multi-ecosystem parsing tests (e.g., test_parse_sbom in tests/parser/)

Step 5 – Create Branch

Default flow (no Target PR):

Create a feature branch named after the Jira issue:

git checkout -b

Target PR flow:

When Target PR is present (parsed in Step 1), check out the existing PR branch instead of creating a new one:

1. Resolve the PR's head branch name:

   gh pr view <pr-number> --json headRefName -R <owner/repo>
   

2. Check out and update the branch:

   git checkout <branch-name>
   git pull
   

This ensures the fix commits are added to the existing PR branch.

Step 6 – Implement Changes

The Description section is your primary specification — implement exactly what it describes. Use Files to Modify, Files to Create, and API Changes as your working scope. Follow the Implementation Notes for patterns and code references on how to implement the changes.

Reuse first: Before writing new logic, check whether the Implementation Notes list reusable code (utilities, helpers, shared modules). If they do, use or extend the existing code. If you discover additional reusable code during implementation that was not listed, prefer reusing it over creating duplicated logic.

Follow conventions: Apply the conventions discovered during Step 4's convention conformance analysis. When writing new code, match the patterns found in sibling files rather than inventing new approaches. If any Implementation Notes or task instructions conflict with a discovered convention, follow the guidance obtained from the user during Step 4.

Serena symbolic editing (preferred)

Use the dedicated Serena instance for the task's repository (look up the instance name in the project's Repository Registry):

• replace_symbol_body — rewrite an entire function, method, struct, or component
• insert_after_symbol / insert_before_symbol — add new code relative to existing symbols
• rename_symbol — rename a symbol and automatically update all references

File-based editing (fallback)

Use Edit/Write tools for non-code files, config files, or when Serena is unavailable.

For each file in Files to Modify:

• Read the current code (or use get_symbols_overview + find_symbol to read selectively)
• Apply the described changes
• Follow existing patterns

For each file in Files to Create:

• Use the patterns referenced in Implementation Notes
• Ensure proper integration (module registration, imports, etc.)

For API Changes:

• Implement endpoint logic
• Update OpenAPI spec if applicable

Cross-repo API contract verification

When the task involves writing manual REST calls — HTTP requests written directly using fetch(), axios, or similar rather than an auto-generated API client — verify the endpoint contract against the backend repository before writing the call.

1. Detect manual REST calls: review the task's Description and Implementation Notes for indicators of manual REST calls. Look for:
   • Explicit endpoint paths (e.g., /api/v2/sboms)
   • References to fetch(), axios, or HTTP client usage
   • Notes stating the auto-generated client is not yet available
   • A "Backend API contracts" subsection in Implementation Notes (added by plan-feature)
2. Look up the backend Serena instance: consult the Repository Registry in the project's CLAUDE.md to find the Serena Instance for the backend repository that serves the API. Tools are called as mcp__<serena-instance>__<tool>.
3. Verify each endpoint: for every endpoint the task will call, use the backend Serena instance (or Grep/Read as fallback) to confirm:
   • The endpoint path exists in route definitions
   • The HTTP method matches
   • The request body shape or query parameters match what the frontend will send
   • The response body shape matches what the frontend will consume (field names, types, nesting structure)
   • The sort order of list responses, when the frontend depends on positional selection (see step 6 below for the detailed verification process)
4. Flag mismatches: if any endpoint path, method, or shape does not match the backend implementation, stop and report the discrepancy to the user before writing the frontend code. Include:
   • What the task description or Implementation Notes specify
   • What the backend actually implements
   • The backend source file and line where the endpoint is defined
5. Proceed with verified contracts: once all endpoints are confirmed, use the verified paths and shapes when writing the manual REST calls. Include a code comment referencing the backend source file for each manual call, so future maintainers can trace the contract origin.
6. Verify sort order for list endpoints: when the frontend consumes a list endpoint and selects a specific element by position (e.g., items[0] for "latest", items[items.length - 1] for "oldest"), verify the backend's actual sort order before relying on positional selection.
   • Detect positional dependence: review the task's Description, Implementation Notes, and frontend code for patterns that assume a specific ordering of list responses. Look for: array index access on response data (e.g., response.data[0]), .first() / .last() calls, destructuring the first element (const [latest] = items), or comments indicating "newest", "most recent", "latest".
   • Inspect the backend sort order: use the backend Serena instance (or Grep/Read as fallback) to find the query builder, ORM query, or SQL statement that populates the list response. Look for ORDER BY clauses, .sort() calls, or sort parameters in the query builder. Check whether a default sort is applied when no explicit sort parameter is provided by the caller.
   • Compare expectations: confirm that the backend's sort order matches the frontend's positional assumption. For example, if the frontend picks items[0] expecting the newest item, verify the backend sorts by created_at DESC (or equivalent), not created_at ASC.
   • Flag sort order mismatches: if the sort order does not match the frontend's assumption, stop and report the discrepancy to the user. Include:
     • What the frontend assumes (e.g., "picks assessments[0] expecting newest")
     • What the backend actually returns (e.g., "ORDER BY created_at ASC — oldest first")
     • The backend source file and line where the sort is defined
     • A recommendation: either fix the frontend to sort explicitly or use a query parameter, or request a backend change

If no Serena instance is available for the backend repository, use Grep, Glob, and Read on the backend repo to perform the same verification.

Example output:

Cross-repo API verification results:

• GET /api/v2/sboms — path ✓, method ✓, response shape ✓ (matches SbomSummary in modules/fundamental/src/sbom/model/summary.rs)
• DELETE /api/v2/sbom/{id} — path ✗ — MISMATCH (backend uses /api/v2/sboms/{id} with trailing 's', see modules/fundamental/src/sbom/endpoints/mod.rs:48)
• GET /api/v2/risk-assessment/group/{groupId} — sort order ✗ — MISMATCH (frontend picks assessments[0] expecting newest, but backend returns ORDER BY created_at ASC — oldest first, see modules/risk/src/assessment/endpoints/mod.rs:92)

Code quality practices

After implementing code changes, verify the following quality practices:

• Documentation on new symbols: every new struct, class, type, interface, enum, and public/exported function must have a documentation comment using the language's convention. One line describing what it is and what it's for is sufficient. For functions where the name alone does not convey the full intent, add a brief explanation of behavior, parameters, or return value so that human reviewers can understand the code without reading the implementation.

Documentation impact

After implementing code changes, evaluate whether documentation needs updating:

1. Check if the task includes a Documentation Updates section — if so, apply those updates.
2. If no Documentation Updates section exists, check the documentation files identified in Step 4:
   • If public APIs, CLI commands, or endpoints were added or changed, update related API docs.
   • If configuration options or setup steps were modified, update related guides.
   • If architectural patterns were changed, update architecture docs.
3. Keep documentation updates lightweight and scoped — only update docs directly impacted by the changes.

Step 7 – Write Tests

Implement the tests described in Test Requirements.

Follow test conventions: Apply the test conventions discovered during Step 4's test convention analysis. When writing new tests, match the assertion patterns, response validation style, error case coverage, and naming conventions found in sibling test files rather than inventing new approaches.

Prefer value-based assertions over length-only checks: When verifying collections or response data, assert on the actual values — not just the count. Assert on specific items or key fields so that test failures reveal what changed, not just how many. Length checks alone hide regressions behind a passing count and prevent subsequent assertions from running.

Prefer parameterized tests for repetitive cases: When multiple test cases exercise the same behavior with different inputs and expected outputs, use the project's parameterized test mechanism instead of writing individual test functions for each case. Apply the Meszaros heuristic as the decision boundary: parameterize when tests share the same algorithm (setup, action, assertion structure) with different data; use individual tests when behavior, setup, or assertions differ between cases. If the test body would need conditionals to handle parameter variations, use separate tests instead. Common mechanisms include JUnit 5 @ParameterizedTest, Mocha/Jest forEach/data arrays, pytest @pytest.mark.parametrize, Go table-driven tests, and Rust rstest. However, if the sibling test analysis in Step 4 shows the project does not use parameterized tests, do not introduce them — follow the project's existing test patterns instead.

Document every test function: Add a documentation comment before every test function explaining what it verifies — a single line using the language's doc comment convention (e.g., /// in Rust, /** */ in Java/TypeScript, """ docstring in Python). This applies regardless of whether sibling tests have documentation; AI-generated tests introduce this as a new standard that overrides the "Follow test conventions" guidance above for documentation specifically.

For non-trivial tests — those with distinct setup, action, and assertion phases — also add given-when-then section comments (// Given, // When, // Then) inside the test body to make the structure navigable at a glance. A test is trivial (skip given-when-then) when it has a single assertion with no distinct setup phase.

Example (Rust):

/// Verifies that an SBOM with no dependencies produces an empty risk score.
#[test]
fn test_empty_sbom_risk_score() {
    // Given an SBOM with no dependencies
    let sbom = create_test_sbom(vec![]);

    // When calculating the risk score
    let score = calculate_risk(&sbom);

    // Then the score should be zero
    assert_eq!(score, RiskScore::default());
}

The doc comment convention varies by language — use /// for Rust, /** */ for Java/TypeScript, """docstring""" for Python, // doc comments for Go, etc.

Run tests to verify:

cargo test (for Rust) npm test (for TypeScript)

Fix any failures before proceeding.

Step 8 – Verify Acceptance Criteria

Go through each Acceptance Criterion and verify it is satisfied. If any criterion cannot be met, stop and explain to the user.

Step 9 – Self-Verification

Before committing, verify that all changes are in scope and free of common errors.

Scope containment

1. Run git diff --name-only to list all modified and created files.
2. Compare the list against the Files to Modify and Files to Create parsed in Step 1.
3. If any file is out-of-scope (not listed in either section):
   • List the out-of-scope file(s).
   • Explain why each was modified.
   • Ask the user to approve or revert each out-of-scope change.
   • Do not proceed to commit without explicit user approval for every out-of-scope file.

Untracked file check

The scope containment check above uses git diff --name-only, which only lists tracked file changes. Untracked files created during implementation — especially those referenced by code via compile-time includes (include_str!, include_bytes!), static imports, or configuration references — would be silently omitted from the commit.

1. List untracked files: run git status --short and extract entries prefixed with ?? (untracked files).
2. Filter by proximity: from the untracked files, keep only those whose parent directory matches a directory that contains at least one modified or created file (from the git diff --name-only output). This focuses the check on directories where implementation work occurred, ignoring unrelated untracked files elsewhere in the repo.
3. Search for code references: for each proximity-matched untracked file, search the staged diff and modified files for references to its filename or relative path. Look for patterns such as:
   • Compile-time includes (include_str!("..."), include_bytes!("..."))
   • Import or require statements (import, require, use)
   • Configuration file references (paths in YAML, JSON, TOML, or XML)
   • String literals containing the filename
4. Flag for review: if any untracked file is referenced by code or is in a directory with modified files, list it and ask the user to confirm whether it should be staged for commit. Do not automatically stage untracked files — always ask first.
5. Proceed: once the user has approved or dismissed each flagged untracked file, continue to commit.

Example output:

Untracked file check results:

• src/data/schema.json — REFERENCED by src/parser.rs via include_str!("data/schema.json") — stage for commit?
• src/data/fixtures.json — in directory with modified files but no code references found — stage for commit?

Sensitive-pattern check

Search the staged diff for secrets, credentials, or environment files that should not be committed:

git diff --cached | grep -iE '(password\s*=|API_KEY|SECRET_KEY|BEGIN.*PRIVATE KEY|.env)'

If any match is found, flag it to the user and do not proceed until the issue is resolved.

Documentation currency

If the implementation changed public APIs, configuration options, or setup steps, verify that related documentation files (identified in Step 4) are still accurate. If a doc file describes behavior that was changed and was not already updated in Step 6, update it now. This check is lightweight — only flag docs that directly describe the modified behavior.

Example consistency

If the implementation wrote or modified documentation that includes examples combining narrative text with concrete data structures (mapping tables, code snippets, configuration blocks, example output), verify internal consistency:

1. Identify composite examples: find every example in the changed documentation that contains both a prose description of a scenario and a data structure illustrating it (e.g., a paragraph explaining a mapping followed by a table or JSON snippet showing it).
2. Cross-check entries: for each data structure entry, confirm it matches what the narrative describes. Check field names, values, labels, enum variants, and relationships. Every entry in the data structure must correspond to something stated or implied by the prose, and vice versa.
3. Flag mismatches: if any entry in the data structure contradicts or is absent from the narrative (or the narrative describes something not reflected in the data structure), fix the inconsistency before proceeding.

Duplication check

Search for functions, methods, or logic in the repository that overlap with the code you wrote. Use Grep or Serena's search_for_pattern to look for similar function names, string literals, or algorithmic patterns. If you find that your new code substantially duplicates existing utilities or helpers, refactor to reuse the existing code before proceeding.

CI checks from CONVENTIONS.md

If CONVENTIONS.md was loaded in Step 4 and verification commands were extracted, run every CI check command recorded during the verification commands extraction. Execute each command in sequence. If any command fails, fix the issue before proceeding to the next command.

1. Run all CI check commands: execute each command extracted from the CONVENTIONS.md CI checks section (e.g., formatting, linting, type checking, compilation). These commands are project-specific — do not hardcode or assume which tools the project uses.
2. Run code generation commands: if any code generation commands were extracted (e.g., OpenAPI spec generation, schema generation, code scaffolding), run them now. If they produce file changes, stage those changes for commit alongside the implementation — they are part of the deliverable.
3. Fix failures: if any CI check command fails, fix the underlying issue and re-run the failing command until it passes. Do not skip failing checks.

If CONVENTIONS.md was not found or contained no CI check section, fall back to running the project's standard build or lint step (if one exists) and compare the warning output against the pre-implementation baseline captured during Step 7. If new warnings were introduced, fix them before proceeding.

Data-flow trace

For each new feature or capability implemented, trace the data through its complete lifecycle to catch partial implementations:

1. Identify data-flow stages: for each change, determine the input (where data enters the system — API request, file read, user event), processing (where it is validated, transformed, or enriched), and output (where results are produced — response, persistence, UI render, event emission).
2. Verify connections: confirm that each stage is connected to the next. A new API endpoint must not just parse a request but also invoke the processing logic and return or persist the result. A new parser must propagate its output to consumers.
3. Flag incomplete paths: list any data-flow path where a stage is missing or disconnected. For each gap, state which stage is incomplete and what is missing.
4. Fix before committing: if incomplete paths are found, implement the missing connections before proceeding. If the missing stage is intentionally out of scope for this task, ask the user to confirm.

Output the traced data flows and their completeness status to the user before proceeding.

Example output:

Data-flow trace results:

• POST /api/v2/sbom → parse request ✓ → validate ✓ → persist to DB ✓ → return response ✓ — COMPLETE
• parseLicense() → extract license ID ✓ → resolve to SPDX ✓ → attach to package ✗ — INCOMPLETE (output not connected)

Contract & sibling parity

Verify that modified or created code fully honors its type contracts and maintains parity with sibling implementations.

Contract verification

1. Identify contracts: for each file modified or created, determine whether the code implements or extends any interface, trait, abstract class, protocol, or type contract. Use Serena's find_symbol or Grep to locate the contract definition.
2. Check completeness: verify that all required methods, properties, and type signatures defined by the contract are implemented. Check that return types cover all variants (e.g., both sync and async, both success and error paths, all union/enum members).
3. Check semantics: verify that method signatures match the contract — parameter types, return types, and nullability/optionality must align.
4. Flag gaps: list any missing or incomplete contract implementations. For each gap, state which contract member is missing and what is required.

Sibling parity analysis

1. Identify siblings: reuse the sibling files identified during the convention conformance analysis in Step 4. If no siblings were identified (e.g., the file is unique), skip this analysis.
2. Compare capabilities: for each sibling, compare cross-cutting concerns against the new or modified code:
   • Shared capabilities (e.g., all providers support CRUD, all handlers validate input)
   • Error handling (e.g., all siblings wrap errors the same way)
   • Logging and observability (e.g., all siblings log at the same points)
   • Configuration options (e.g., all siblings accept the same option types)
3. Flag parity gaps: list any capabilities present in siblings but missing from the new implementation. For each gap, state which sibling provides the capability and what is missing.
4. Fix or confirm: if gaps are found, fix them before proceeding. If a gap is intentional (the new code deliberately omits a capability), ask the user to confirm before proceeding.

Cross-module shared entity analysis

Sibling parity (above) compares files in the same directory or module. When the implementation inserts into, updates, or deletes from a shared database entity (table, collection, or document store) that is used by multiple modules, extend the analysis across module boundaries to detect pattern inconsistencies.

1. Identify shared entities: for each database operation in the new or modified code (e.g., insert(), update(), delete(), ORM save/create calls, raw SQL), determine the target entity (table name, model class, or schema object).
2. Search cross-module: use Serena's search_for_pattern (or Grep as fallback) to find all other modules that interact with the same entity. Look for:
   • Insert/upsert operations on the same table or model
   • Update or delete operations that reference the same entity
   • Schema definitions or migrations for the entity
3. Compare patterns: for each cross-module usage found, compare:
   • Transaction handling (e.g., nested/savepoint transactions vs. bare operations)
   • Constraint handling (e.g., duplicate-key/conflict handling, ON CONFLICT clauses, try/catch around unique violations)
   • Error handling (e.g., how constraint violations are caught and reported)
   • Data validation (e.g., pre-insert checks, foreign key verification)
   • Locking strategies (e.g., SELECT FOR UPDATE, advisory locks)
4. Flag cross-module anomalies: if the new code uses a pattern that differs from how other modules interact with the same entity, flag it as a potential anomaly. State what the new code does, what the other module(s) do instead, and which files contain the differing pattern.
5. Fix or confirm: if anomalies are found, align the new code with the established cross-module pattern before proceeding. If the deviation is intentional, ask the user to confirm before proceeding.

Example output:

Cross-module shared entity analysis results:

• Entity source_document — 2 modules interact:
  • ingestor/graph/mod.rs: uses nested transaction with ON CONFLICT DO UPDATE for duplicate-key handling
  • risk_assessment/service/mod.rs (new code): uses plain insert() with no conflict handling — ANOMALY
  • Recommendation: adopt the ingestor's ON CONFLICT pattern to handle duplicate inserts gracefully

Caller-site parity

When the implementation creates or modifies code that calls a shared abstraction (e.g., a mutation hook, API client method, service function, event emitter), verify that the call site follows the same patterns as existing callers of that abstraction.

Sibling parity (above) checks the definition of shared code; caller-site parity checks how consumers invoke it. This catches anti-patterns introduced at the call site — such as window.location.reload() in a mutation success callback when no other caller in the codebase uses that pattern.

1. Identify shared abstractions called: for each new or modified call site, determine the shared abstraction being invoked (e.g., a custom hook like useDeleteSbomMutation, an API client method like apiClient.post(), a service function like notifyUser()).
2. Find existing callers: use Grep or Serena's find_referencing_symbols / search_for_pattern to locate all other call sites of the same abstraction in the codebase.
3. Compare call-site patterns: for each existing caller, compare:
   • Success/completion handling (e.g., what happens in onSuccess, .then(), or after await — do callers use router navigation, cache invalidation, toast notifications, or state updates?)
   • Error handling (e.g., onError, .catch() — do callers show error toasts, log errors, or retry?)
   • Side effects (e.g., do callers trigger page reloads, modify global state, or dispatch events? Are these side effects consistent across callers?)
   • Parameter patterns (e.g., do callers pass the same option shapes, use the same defaults?)
4. Flag caller-site anomalies: if the new code uses a pattern that no existing caller uses (e.g., window.location.reload() when all other callers use queryClient.invalidateQueries()), flag it as a potential anti-pattern. State what the new code does, what existing callers do instead, and how many existing callers were checked.
5. Fix or confirm: if anomalies are found, align the new code with the established caller pattern before proceeding. If the deviation is intentional, ask the user to confirm before proceeding.

Output the contract verification, sibling parity, cross-module shared entity, and caller-site parity results to the user before proceeding.

Example output:

Contract & sibling parity results:

• StorageProvider implements Provider trait — get() ✓, list() ✓, delete() ✓, update() ✗ — GAP (missing update method)
• Sibling parity with S3Provider, GcsProvider:
  • Retry logic ✓ (all siblings use exponential backoff)
  • Logging ✗ — StorageProvider missing info!() on successful operations — GAP
  • Config options ✓ (all accept ProviderConfig)
• Caller-site parity for useDeleteSbomMutation:
  • 3 existing callers found: SbomList.tsx, SbomDetail.tsx, SbomActions.tsx
  • Success handling: all use queryClient.invalidateQueries() + toast notification
  • New code uses window.location.reload() — ANOMALY (0 of 3 callers use this pattern)
  • Error handling ✓ (all callers including new code use onError toast)

Step 10 – Commit and Push

Commit following the Conventional Commits specification (https://www.conventionalcommits.org/en/v1.0.0/):

git commit --trailer="Assisted-by: Claude Code" -m "[optional scope]:

[optional body]

Implements "

Where type is one of: feat, fix, refactor, test, docs, chore, etc. Use a scope when relevant (e.g. feat(api): add AIBOM endpoint). The footer MUST reference the Jira issue ID. Always include --trailer="Assisted-by: Claude Code" to attribute AI assistance.

Default flow (no Target PR):

Push the branch and open a pull request. In the PR description, use a Markdown link for the "Implements" line so the Jira issue is clickable:

Implements

where <webUrl> is the issue URL captured in Step 1 (e.g. Implements [PROJ-231](https://redhat.atlassian.net/browse/PROJ-231)).

If a GitHub issue reference was extracted in Step 1, append a Closes <owner>/<repo>#<number> line to the PR description body. GitHub recognizes this keyword and will auto-close the linked issue when the PR is merged. Do not add this to the commit message — only the PR description.

Target PR flow:

When Target PR is present, push to the existing branch and update the PR description instead of creating a new PR:

1. Push the new commit(s) to the existing branch:

   git push
   

2. Update the PR description to reflect the additional changes:

   gh pr edit <pr-number> -R <owner/repo> --body "<updated-description>"
   

   Add the current task's Jira issue ID to the PR description's Summary section (e.g., a new bullet point describing the fix). Preserve the existing PR description content — only append to the Summary bullets.

Step 11 – Update Jira

Default flow (no Target PR):

Look up the Git Pull Request custom field ID from the project's Jira Configuration section in CLAUDE.md (the field is listed as Git Pull Request custom field: <field-id>).

• If configured, update that custom field on the Jira issue with the PR URL. The field requires ADF (Atlassian Document Format), not a plain string:

jira.update_issue(, fields={"": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "inlineCard", "attrs": {"url": ""}}]}]}})

• If not configured, skip the custom field update — the PR link will still be included in the Jira comment below.

Add a comment to the Jira task:

jira.add_comment

Include:

• PR link
• Summary of changes made
• Any deviations from the plan

Transition the task:

jira.transition_issue → In Review

Target PR flow:

When Target PR is present, use the PR URL from the Target PR section (not a newly created PR). Skip the custom field update — the PR link was already set when the original task's PR was created.

Add a comment to the Jira task:

jira.add_comment

Include:

• PR link (from Target PR)
• Summary of fix changes made
• Reference to the review feedback that triggered the fix

Transition the task:

jira.transition_issue → In Review

Important Rules

• Do not guess — use the Serena instance specified in the project's Repository Registry (CLAUDE.md) for the target repo, with tools like get_symbols_overview, find_symbol, find_referencing_symbols to inspect code before modifying it. Check the Code Intelligence section for per-instance limitations. Fall back to Read/Grep/Glob for repos without a Serena instance.
• Follow the Implementation Notes closely — they reference real code patterns.
• If the structured description is incomplete, ask the user rather than improvising.
• Keep changes scoped to what the task describes — no unrelated refactoring.
• Every commit must reference the Jira issue ID.
• If the same test fails 3 times with the same error, stop and ask the user for guidance — do not retry the same approach.
• If the same file is edited more than 5 times for the same change, stop and reassess your approach — present the problem and proposed alternatives to the user.
• If a build or compile error persists after 2 fix attempts, stop and present the error and proposed alternatives to the user — do not keep trying the same fix.