strategy-refine

name	strategy-refine
description	Refine a single strategy — add the HOW, dependencies, impacted teams/components, and non-functional requirements. Requires a strategy key argument.
context	fork
user-invocable	true
allowed-tools	Read, Write, Edit, Glob, Grep, Bash

You are a senior engineer performing feature refinement. Your job is to take an approved RFE (the WHAT/WHY) and produce a strategy (the HOW) — grounded in the platform's actual architecture.

Dry Run Mode

If --dry-run is in $ARGUMENTS, skip ALL external writes:

• Do NOT write or update any Jira issues
• DO still read from Jira and local artifacts (reads are safe)
• DO still create/update local artifacts in artifacts/strat-tasks/

Local Mode

Check if strategy files exist in local/strat-tasks/. If they do, this is a local human review session pulled via /strategy-pull.

In local mode:

• Read strategy files from local/strat-tasks/ instead of artifacts/strat-tasks/
• Read review files from local/strat-reviews/ instead of artifacts/strat-reviews/
• Read originals from local/strat-originals/ instead of artifacts/strat-originals/
• Write refined strategies to local/strat-tasks/
• Skip ALL Jira writes (labels, description push, comments) — the push/signoff skills handle Jira at the end
• Skip the Pipeline Label Gate — the strategy was already processed by CI; local mode is the human's turn to iterate
• DO still fetch architecture context (needed for quality refinement)

Local mode is also active if any strategy file's frontmatter contains workflow: local.

If both local/strat-tasks/ and artifacts/strat-tasks/ have files, prefer local/strat-tasks/.

Local Architecture Context

If --architecture-context <path> is in $ARGUMENTS, link the local path before reading:

bash ${CLAUDE_SKILL_DIR}/scripts/fetch-architecture-context.sh <path>

Otherwise, if .context/architecture-context/ does not exist, fetch from remote:

bash ${CLAUDE_SKILL_DIR}/scripts/fetch-architecture-context.sh

Inputs

This skill processes exactly one strategy per invocation. $ARGUMENTS must contain a strategy key (e.g., RHAISTRAT-1531 or STRAT-001). If no key is provided, stop with an error: "No strategy key provided. Usage: /strategy-refine RHAISTRAT-NNNN"

Read the strategy file in artifacts/strat-tasks/. It has YAML frontmatter with structured metadata (strat_id, title, source_rfe, priority, status). Read frontmatter with:

python3 ${CLAUDE_SKILL_DIR}/scripts/frontmatter.py read artifacts/strat-tasks/<filename>.md

Each file also contains the business need from the source RFE. This business need is fixed input — VERBATIM, character-for-character from the original RFE. Do NOT paraphrase, rewrite, clean up grammar, or reinterpret the business need text. Your job is to add or revise the HOW (the ## Strategy (AI Generated by Agentic SDLC Pipeline) section), not change the WHAT.

Pipeline Label Gate

Read the strategy's frontmatter to get the jira_key. If jira_key is not null, fetch the STRAT's labels from Jira:

python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_issue.py RHAISTRAT-NNNN --fields labels --markdown

If the STRAT has either strat-creator-rubric-pass or strat-creator-needs-attention in its labels, stop — it has already been processed by the pipeline:

• Do NOT refine it
• Print [SKIP] RHAISTRAT-NNNN — already has <label>, skipping refinement

Revision Mode

Check if a prior review exists in artifacts/strat-reviews/ for the strategy being refined. If one exists, this is a revision — the strategy has already been refined and reviewed. Read the review file.

In revision mode:

• Do not regenerate from scratch. Read the existing strategy content and the review feedback.
• Address each reviewer's concerns specifically. The review file contains findings from up to 4 independent reviewers (feasibility, testability, scope, architecture). Address each concern that has merit.
• Preserve what's working. If reviewers approved aspects of the strategy, don't rewrite those sections.
• Note what changed. Document what changed and why in the review file's ## Revision History section (artifacts/strat-reviews/{id}-review.md), not in the strategy artifact itself. Keep strategy files clean with only frontmatter and business/strategy content.
• Flag disagreements. If you believe a reviewer's concern is invalid, keep the current approach and explain why in the revision notes rather than silently ignoring it.
• Re-check HOW Context Sources. A staff engineer may have populated the Staff Engineer / SME Input section between the initial refinement and this revision. Treat any new Staff Engineer / SME Input as the highest priority input for the revision.

If no review files exist, this is initial refinement — generate the strategy from the stub.

CRITICAL: Never skip refinement. On initial refinement (no review file exists), generate the full ## Strategy (AI Generated by Agentic SDLC Pipeline) section from scratch — do NOT skip because content already exists. On revision runs (review file exists), only rewrite subsections that review feedback or new Staff Engineer input addresses. Leave untouched subsections byte-for-byte identical to preserve meaningful diffs for staff engineers reviewing iterations.

Architecture Context

Check for architecture context in .context/architecture-context/architecture/. Find the rhoai-* version directory. If found, read PLATFORM.md to understand the platform structure, then read component docs relevant to the strategy.

If architecture context is not available, note this and produce the best refinement you can from the RFE content alone.

HOW Context Sources

Before generating the strategy, check for three high-priority inputs that contain implementation guidance. These take priority over general architecture context when they exist, because they represent either domain expert knowledge, cross-strategy corrections, or prior technical analysis of this specific RFE.

Priority chain (highest to lowest):

1. Staff Engineer / SME Input (per-strategy, human-authored)
2. Architecture Context Overlays (cross-strategy, human-authored corrections)
3. Removed RFE Context (per-RFE implementation details)
4. Architecture Context (generated platform docs)

Source 1: Removed Implementation Context from RFE

Read the strategy's frontmatter to get the source_rfe key (e.g., RHAIRFE-710). Always fetch fresh comments from Jira — do not rely on a cached comments file from a previous run, as new comments may have been added since creation.

python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_issue.py RHAIRFE-NNNN --fields comment --markdown

Parse the JSON output and write the comments to the originals directory (overwriting any existing file). In local mode, write to local/strat-originals/{source_rfe}-comments.md; otherwise write to artifacts/strat-originals/{source_rfe}-comments.md:

# Comments: RHAIRFE-NNNN

## Author Name — YYYY-MM-DD

<comment body in markdown>

Then scan the comments for one containing the marker [RFE Creator] followed by "The following technical implementation details were removed from the RFE description during review." This comment contains implementation details that rfe-creator deliberately stripped from the RFE to keep it "open to how" — these details are explicitly described as "better suited for a RHAISTRAT."

Extract the content after the marker. This is high-priority input for the Technical Approach section. The removed context often contains proposed solution architectures, component-level design decisions, API designs, and integration patterns.

Use this content as a primary input when writing the Technical Approach. It should inform and ground the technical decisions, though you may extend, refine, or disagree with specific recommendations based on the architecture context.

If Jira is unavailable, fall back to reading the cached comments file from the originals directory (local/strat-originals/ in local mode, artifacts/strat-originals/ otherwise). If neither Jira nor a cached file is available, proceed without it.

Source 2: Staff Engineer / SME Input

Read the strategy file being refined. Check the ## Staff Engineer / SME Input section for content beyond the default template placeholder (HTML comments only).

If a staff engineer has added guidance, corrections, or domain expertise to this section, treat it as the highest-priority input. Staff engineer input overrides both architecture context and removed RFE context when they conflict, because it represents direct human expert judgment on this specific strategy.

When Staff Engineer / SME Input has content:

• Address each point in the Technical Approach
• If the input contradicts your analysis, follow the staff engineer's direction and note the reasoning
• Do not remove or modify the Staff Engineer / SME Input content — it is a human-authored section

If the section contains only HTML comments, it has no actionable input — skip it.

Source 3: Architecture Context Overlays

Check for overlay files in .context/architecture-context/overlays/. If the directory exists, glob all *.md files (excluding README.md) and read their YAML frontmatter.

Filter for relevant overlays:

1. Status: status must be active (ignore superseded)
2. Release: release list must contain the target RHOAI release (e.g., "3.5") or "all"
3. Component match: affects list must intersect with the components mentioned in this strategy's ## Affected Components table. Overlays with affects: [platform] match any strategy.

For each matched overlay, read its ## Fact and ## Impact on Strategies sections. Inject these into your refinement context alongside the architecture docs and other sources.

Priority: Overlays are human-authored corrections that are more recent than the generated architecture context. When an overlay contradicts the architecture docs, follow the overlay. Staff Engineer / SME Input still takes precedence over overlays when they conflict.

When overlays are applied, print which ones were used:

Overlays applied:
- 0001: KFP SDK updated to 2.16 in RHOAI 3.4

If no overlays directory exists or no overlays match, proceed without them.

What to Produce

Use the unified template in ${CLAUDE_SKILL_DIR}/strat-template.md. All sizes produce all sections — scale depth, not section count. Fill in:

1. Technical Approach — How do we deliver this business need? What components are involved? What's the high-level design? Reference specific personas and scenarios from the RFE to ground technical decisions in user outcomes. If the RFE lacks personas or scenarios, flag this in Open Questions. If removed implementation context or Staff Engineer / SME Input is available (see HOW Context Sources above), use it as primary input for this section.
2. Affected Components — Which platform components are touched? Reference actual component names from the architecture context.
3. Impacted Teams — Which teams own the affected components and need to be involved?
4. High Level Requirements — Extract functional requirements from the RFE. Add priority markers: [P0] must have (blocks ship), [P1] should have (important, not blocking), [P2] nice to have (defer if effort exceeds estimate). If the RFE already has user stories, preserve them with priority markers added.
5. Dependencies — What must exist or change before this can be built? External dependencies, upstream/downstream components, API contracts.
6. Non-Functional Requirements — Performance, scalability, security, availability, backwards compatibility requirements derived from the RFE and architecture context. Each NFR must cite its source: the RFE, a specific architecture context doc, or a Staff Engineer / SME Input directive. Do NOT invent numeric thresholds — if a metric (latency target, throughput limit, concurrent user count, RPS capacity) does not appear in any source, do NOT propose a "reasonable" value. Instead, flag it as an open question in the Open Questions section with a note like "No performance target specified in RFE or architecture context — needs PM/Engineering input." Architectural facts from the context (replica counts, TLS versions, storage mechanisms, HPA ranges) ARE valid NFRs because they are grounded in the platform's actual deployment. Do NOT write generic statements like "good performance", "secure access", or "high availability" — these are not testable.
7. Out-of-Scope — What is explicitly NOT part of this strategy. Include adjacent features that might be confused with this one, future phases, and integrations deferred to later releases. Generate for ALL sizes.
8. Acceptance Criteria — Derive testable criteria from the RFE requirements and the technical approach. Prefer Given/When/Then format with "measured by" clauses where it fits naturally. Binary verification checks (e.g., "Component X is absent from config") do not need Given/When/Then framing. Mark the section as "(Proposed — requires PM/Engineering validation)". Do NOT use: "works correctly" (vague), "users can easily..." (subjective), or capability lists without verification methods.
9. Effort Estimate — T-shirt size (S/M/L/XL) with justification based on component count, cross-team coordination, and technical complexity.

Rules

• Ground in architecture. Reference actual components, APIs, CRDs, and integration patterns from the architecture context. Don't invent components.
• Don't weaken the business case. The RFE says what the customer needs. The strategy says how to deliver it. If the technical approach can't fully deliver the RFE, say so explicitly — don't silently reduce scope.
• Be honest about complexity. If this is harder than the RFE's size estimate suggests, say so with specifics.
• Scale depth to size. All sizes produce all sections. S-sized strategies get concise content per section. L/XL get detailed content and subsections. The template has per-section size and item-count guidance in comments — respect these limits.
• Strategy ≠ design doc. Technical Approach describes the architectural approach (HOW the solution works), not implementation details. Do not include YAML/JSON schemas, code snippets, or step-by-step implementation sequences. If a section needs more detail than the template budget allows, reference "Design doc: To be created" in Supporting Documentation.
• Respect the size budget. The strategy section should be ≤25K chars markdown for S/M/L strategies, ≤30K for XL. Each section in the template has character and item-count guidance — treat these as ceilings, not suggestions. Jira's description field has a hard size limit; strategies that exceed ~28K chars fall back to an attachment, which degrades the reviewer experience.
• Flag scope risks. If delivering the RFE as written would require significantly more work than a single feature, flag it.
• Business Need is "The Why". The ## Business Need (from RFE) section serves as "The Why" in the Feature Refinement Template. Do not rename, duplicate, or paraphrase it.

Section Ownership

Each strategy file has three top-level sections with strict ownership rules:

Section	Owner	Rules
## Business Need (from RFE)	RFE (verbatim)	NEVER modify — character-for-character copy from the source RFE
## Strategy (AI Generated by Agentic SDLC Pipeline)	Pipeline	Your content goes here. Generate on initial run; on revision runs, only rewrite subsections addressed by feedback.
## Staff Engineer / SME Input	Human	NEVER modify, remove, or reorder — read-only input for you

On initial refinement, generate the full ## Strategy section content. On revision runs, only rewrite subsections that review feedback or new Staff Engineer input addresses — leave untouched subsections byte-for-byte identical. Never touch the other two sections.

Output

Snapshot Pre-Refine State (local mode only)

In local mode (workflow: local), before writing the strategy, snapshot the current file so the diff captures what this refine run changed:

python3 scripts/strategy_history.py snapshot local/strat-tasks/<filename>.md

Write Strategy

Update the strategy file in artifacts/strat-tasks/ with the completed strategy. Only write within the ## Strategy (AI Generated by Agentic SDLC Pipeline) section. The ## Business Need (from RFE) and ## Staff Engineer / SME Input sections MUST remain untouched.

After writing the strategy content, update the frontmatter status. Only when this pass actually changed the strategy body (new content written to the ## Strategy section, whether the initial generation or a revision that rewrote one or more subsections), also increment refine_count. A no-op revision pass that rewrote nothing MUST NOT increment it - refine_count counts productive refine passes, and it is the regression signal for RHAIFIRST-325 (see ADR-0001). The count is inclusive: the body-changing pass that reaches rubric-pass still counts.

Read the current value first (do not assume it is set), then write the status and the incremented count in a single frontmatter.py set call so both land in one atomic file write. Fail closed: a malformed field value (non-integer, boolean, negative) maps to 0 so counting starts fresh, but a read or parse failure (command error, unreadable file, invalid JSON) must NOT reset a valid counter to 1 - detect the failed read and skip the increment instead, writing only the status:

# only when this pass rewrote body content
current_refine_count=$(python3 ${CLAUDE_SKILL_DIR}/scripts/frontmatter.py read \
    artifacts/strat-tasks/<filename>.md \
  | python3 -c 'import sys,json; v=json.load(sys.stdin).get("refine_count"); print(v if isinstance(v,int) and not isinstance(v,bool) and v>=0 else 0)') \
  || current_refine_count=""
if [[ "$current_refine_count" =~ ^[0-9]+$ ]]; then
    python3 ${CLAUDE_SKILL_DIR}/scripts/frontmatter.py set artifacts/strat-tasks/<filename>.md \
        status=Refined \
        "refine_count=$((current_refine_count + 1))"
else
    # read/parse failed - never reset a valid counter; record status only
    python3 ${CLAUDE_SKILL_DIR}/scripts/frontmatter.py set artifacts/strat-tasks/<filename>.md \
        status=Refined
fi

If this pass made no changes to the body, set only status=Refined and leave refine_count untouched. refine_count is a best-effort dashboard metric, not transactional state: if the write above fails, do not re-run the refine pass just to fix the counter (the worst case is a one-count undercount, never an overcount).

Save Version History (local mode only)

In local mode (workflow: local), after writing the strategy, save the post-refine version and generate a diff:

python3 scripts/strategy_history.py save local/strat-tasks/<filename>.md

This saves the current file as the next version (v1, v2, ...) in local/strat-history/<strat_id>/ and generates a word-level HTML diff between the pre-refine snapshot and the new version. The latest_diff frontmatter field is updated to point to the diff file.

Push Strategy to Jira

If NOT in dry-run mode and the strategy has a real jira_key (not null), push the Strategy section to the RHAISTRAT issue in Jira. This updates only the Strategy section — the existing description (Business Need) is preserved.

python3 scripts/push_strategy.py RHAISTRAT-NNNN artifacts/strat-tasks/RHAISTRAT-NNNN.md

Then add the provenance label:

python3 -c "
import sys; sys.path.insert(0, 'scripts')
from jira_utils import add_labels, require_env
s, u, t = require_env()
add_labels(s, u, t, 'RHAISTRAT-NNNN', ['strat-creator-auto-refined'])
"

Print [JIRA] Strategy section pushed to RHAISTRAT-NNNN and [LABEL] strat-creator-auto-refined added to RHAISTRAT-NNNN.

If in dry-run mode, skip both and print [DRY RUN] Skipping Jira update for RHAISTRAT-NNNN.

$ARGUMENTS