feat(tools-triage-flow): ticket triage flow — thin workflow + tools-triage skill

[sergepr]

Adds tools-triage-flow, a flow that triages one issue-tracker ticket per invocation for GD Tools' AI SDLC pipeline (TSSM ticket triage): it elicits requirements from the ticket through comment round-trips, posts a triage assessment, then creates and links a Story in the target TOOL project. It is delivered as a thin workflow plus one flow-owned skill, tools-triage.

This is the Rosetta-side half of a two-repo flow. The trigger (a Jira webhook / CI dispatch) and the PR publishing live in tools-harness-intake and griddynamics/tools-aisdlc-knowledgebase. Wiring those to actually call /tools-triage-flow and to execute the write artifacts it produces is separate, deliberately out-of-scope follow-up work — see Deferred below.

Why the flow looks the way it does

It has no live connection to the Issue Tracker, by design. The caller composes whatever it knows about the ticket into free text and passes it in; the flow never reads anything itself. Every write it decides to make is composed into a JSON artifact on disk for a later executor to run — it never sends one. Two consequences reviewers should hold onto:

• No comment ID, created issue key, URL, or link ID exists at compose time. The five state fields that name one are recordable only as the literal "pending — see <artifact path>" sentinel. A plausible-looking identifier anywhere in this flow would be a fabrication, and the next invocation would trust it.
• Phase 6's create-then-link pair cannot complete in one tick: link_issues needs a real target-project key, which does not exist until someone executes the create artifact and that result reaches a later invocation's input. This is handled as an expected resumable state (create composed, link pending), not a failure.

It is deployment-specific, not a general-purpose Rosetta flow. The target project key TOOL, issue type Story, the TSSM: Tool / TSSM: Project custom fields, and the Grid Dynamics tool-impact reasoning are hardcoded constants for this deployment. There is no config file anywhere in this build.

Architecture: thin workflow + one flow-owned skill

The flow originally shipped as 7 files under workflows/ — a 216-line triage-flow.md plus 6 phase files — which inverted Rosetta's layering. docs/schemas/workflow.md requires the workflow file to stay "small and short, skills already define how things work", yet the workflow carried <intake_contract>, <write_artifact_contract>, <idempotency> and a 42-line <state_and_resumption>. The flow owned no skill at all: deleting the shared jira-write skill earlier in this branch inlined its knowledge into the workflow rather than into a flow-owned skill.

It also polluted the command surface: all 6 phase files were emitted flat into every target's command folder (plugins/core-claude/workflows/, core-cursor/commands/, core-copilot/commands/) and nested under core-codex/.agents/skills/triage-flow/phases/. Their user-invocable: false frontmatter carried through verbatim, but Cursor and Copilot command frontmatter has no such key — so /triage-flow-intake and its five siblings were reachable there as user commands.

Final shape, following the coding-agents-prompting-flow + coding-agents-prompt-authoring pattern already established in this repo:

instructions/r3/core/
  workflows/tools-triage-flow.md    thin orchestration: 6 phase blocks, 149 lines
  skills/tools-triage/
    SKILL.md                        646 lines — role · when_to_use · core_concepts
                                    (cross-stage invariants, stage flow, section map)
                                    · <intake_and_state>  input contract + redaction,
                                      state semantics, change detection, resume routing,
                                      state skeleton
                                    · <elicitation_and_assessment>  one iteration,
                                      completion/routing decision, assessment rubrics,
                                      assessment skeleton
                                    · <writes_and_tool_issue>  compose contract (ops,
                                      NNN, gate, no-identity), the three op JSON shapes,
                                      create-then-link stage
                                    · validation_checklist · pitfalls
    README.md                       44 lines — maintainer doc, never loaded at runtime

3 authored files. Single-file skill: no references/, no assets/. Sections point at each other by tag (`<write_artifacts>` below, `<state_and_idempotency>` above), and each carries its own checklist, pitfalls, and the shape of the file it produces. The trade — recorded in README.md along with the reversal path — is that activating the skill loads all 646 lines, with no partial loading.

The workflow keeps only orchestration: phase sequence, per-phase subagent / role / subagent_required_model / must-be-subagent, state ownership, scope boundary, and a sequencing-and-evidence checklist. It names the skill and the topic per phase and lets the skill route — it does not deep-link into references/, because the closed alias grammar forbids it (SKILL FILE never carries a skill name; skill-folder isolation is grammar-enforced).

Why one skill rather than two or six. A separate write-mechanics skill would recreate the independently-discoverable shared Jira skill that jira-write's deletion was meant to end. Six per-phase skills would burn the shared ~1K-token skill-description budget for a single-caller flow. tools-triage is flow-owned: tools-triage-flow is its only caller, and nothing in it is written for reuse elsewhere.

Why the tools- prefix. triage-flow was a generic name in a shared namespace for a deployment-specific flow, and this repo already uses "triage" for PR/issue triage (.github/workflows/repo-triage.yml). The prefix marks both artifacts as one self-contained unit, stops the skill reading as general-purpose, and leaves triage-flow free for a real generic triage flow. A skill may not take the flow's own name — Codex and Antigravity convert the workflow into a skill of that exact name, so tools-triage (skill) and tools-triage-flow (flow) are deliberately distinct and coexist in those targets.

Input / output

• Input: { ticket_key, reason?, ticket_details, artifacts_dir? }, supplied directly by the caller. ticket_details is free text with no fixed schema — no file read, no config read, no live fetch. artifacts_dir defaults to agents/TEMP.
• Output, all under <artifacts_dir>/<TICKET-KEY>/: <TICKET-KEY>-REQUIREMENTS.md, <TICKET-KEY>-TRIAGE-ASSESSMENT.md, <TICKET-KEY>-TRIAGE-FLOW-STATE.md, and one issue-writes/<NNN>-<op>.json per composed write (op ∈ add_comment, create_issue, link_issues). Executing those against the real tracker is a separate, cross-repo step.
• Idempotency: a SHA-256 hash of this tick's redacted ticket_details versus last_processed_ticket_details_hash. Deliberately coarser than a comment-ID diff — free text carries no comment IDs — so its worst case is an unnecessary elicitation re-run on a no-op text change, never a missed update.

POC-scope overrides — please review these explicitly

Two documented simplifications weaken normal Rosetta gates. Both are flagged in-file with a POC-SCOPE-OVERRIDE: marker naming exactly what they substitute for, and both are prose, not config — removing the paragraph restores the gate.

1. Compose gate (tt-write-artifacts.md): skips dangerous-actions step 5 and hitl's always-require-approval rule for all three compose operations — unattended at compose time by design, matching the unattended-CI posture. The dangerous-actions content gate itself still runs, once per artifact. The override governs only whether an artifact is written to disk; it says nothing about whether executing it later is safe. create_issue is the one exception it does not cover: because a created issue can never be deleted, that compose must state which duplicate-prevention check ran and what it found, or it is refused.
2. Completion rule (tt-elicitation-and-completion.md): "Open Questions empty" alone flips the requirement units to Approved, standing in for hitl's explicit affirmative-sentence approval. The flow's human gate lives downstream, in the consumer of its artifacts (harness-intake's PR review), not in Jira ticket state.

sensitive-data redaction is not relaxed: intake redacts ticket_details itself before anything downstream sees it, and evidence is cited by type/count/location only, never the masked value.

Deferred (seams only, do not implement here)

Real cron/webhook trigger · sub-hourly cadence · any risk-based gating on the assessment levels · local eligibility re-checking · service-account credential swap · changes to tools-harness-intake · post-creation management of the created issue · a comment announcing it · executing the composed artifacts and feeding results back. One known residual gap: this flow cannot live-validate custom-field option values or link-type names before composing — that validation belongs to whatever executes the artifacts.

Verification

• plans/triage-flow-skill-extraction/ carries a 151-row invariant inventory built before any content moved, with every normative rule, constant, rubric level, state field, and regression-preventing negation traced to its new home. Its destination-key table maps each row to the file and section it now lives in.
• Automated needle checks across every destination file — 108 on the first pass, re-run after the rename and again after the file consolidation, each time with zero misses. One miss on the first pass was fixed and re-verified.
• Plugins regenerated across all 7 targets, exit 0. Zero stale triage-flow* or ticket-triage* artifacts remain; exactly one tools-triage-flow command and one tools-triage skill per target, one INDEX entry each.
• data-collection shows zero diff from its pre-branch state; no jira-write references remain anywhere.

Two things recorded honestly rather than smoothed over, both in content-map-verification.md §S6: the workflow deviates from the plan by not deep-linking into the skill (the alias grammar forbids it), and POC-SCOPE-OVERRIDE occurrences dropped 14 → 8 because per-phase restatements of the same compose override were consolidated into the contract of record — both distinct overrides survive with full framing.

Vendor neutrality

The instructions describe an Issue Tracker, not a vendor. Prose mentions of Jira are gone, and the artifact directory is issue-writes/, not jira-writes/. The op names (add_comment, create_issue, link_issues), target_issue_key, and the state-file fields were already neutral. The target constants (TOOL, Story, Action item, TSSM: Tool / TSSM: Project) stay — those are the deployment's real values, not vendor terminology.

One jira string is kept on purpose: a pitfall naming agents/jira-triage.config.json, a config file deleted earlier in this branch. It works precisely because it names the exact file an agent primed on the old design would hunt for.

⚠️ Cross-repo item this PR cannot close: if tools-harness-intake already references jira-writes/, it needs the same rename. The path was safe to change here only because the executor that reads these artifacts does not exist yet.

PR size

44 changed files, of which 30 are generated plugins/** output: npx rosettify-plugins copies every authored file into all 7 agent targets (claude, cursor, cursor-standalone, copilot, copilot-standalone, codex, antigravity), and those outputs are tracked in this repo. The authored surface is 3 files under instructions/r3/core/, plus 8 plan/verification docs and 3 one-line registry entries (docs/definitions/skills.md, workflows.md, agents/IMPLEMENTATION.md).

Worth knowing when reading the commit history: the skill was first authored as 11 files (6 references + 3 assets + SKILL.md + README), consolidated to 5, then inlined to 2. The second and third commits are pure file merges with no behavior change — the needle sweep was re-run after each, always zero misses.

Review guide

Start with content-map-verification.md — each row names a rule and where it lives. Then skills/tools-triage/SKILL.md: it is the entire behavioral surface now. workflows/tools-triage-flow.md is orchestration only. Design history for the earlier decoupling work is in plans/triage-jira-decoupling/HANDOFF.md.

[github-actions]

Rosetta Triage Review

Summary: Adds triage-flow (a 6-phase, tick-based, resumable ticket-triage workflow: intake → elicitation → completion-check → publish-questions/assess → create-tool-issue) plus jira-write, a new write-capable Issue Tracker skill, and the deployment config/MCP wiring (agents/jira-triage.config.json, agents/jira-mcp-auth-header.sh, .mcp.json) needed to run it against Jira. Source-only PR; plugin regeneration is intentionally excluded (build output, not source).

This touches instructions/r3/**, so it was reviewed as instruction-quality content (per this repo's triage policy) with a dedicated Rosetta prompt-authoring subagent review, cross-checked against docs/schemas/workflow.md, docs/schemas/skill.md, and sibling instruction files.

Findings:

• jira-write/references/jira-write-vendor-binding.md, triage-flow.md, and triage-flow-intake.md all name data-collection's private reference file issue-vendor-binding.md by filename. Per pa-hardening.md's cross-skill isolation rule, another skill's internal references/ files must never be named directly — only "USE SKILL data-collection to ..." intent phrasing is allowed.
• All subagent_required_model lists across the 6 new phase files use R2-era model IDs (claude-4.8-opus-high, gpt-5.5-high, gemini-3.1-pro-high, gpt-5.4-low) rather than the current R3 canonical set used consistently elsewhere in instructions/r3 (claude-opus-5, gpt-5.6-sol/terra/luna, gemini-3.7-flash).
• triage-flow.md's frontmatter description and jira-write/SKILL.md's description both run well past the schema's ~15-token / pa-hardening's <30-token cap (roughly 2x over on the workflow file).
• jira-write/SKILL.md's <dangerous_actions_gate> claims steps 1–4 of dangerous-actions "still run" while skipping step 5, but dangerous-actions/SKILL.md defines one atomic 5-step process with no documented provision for partial invocation — the "content-level check still applies" claim isn't actually licensed by the skill it's overriding.
• The POC-SCOPE-OVERRIDE in jira-write disables human confirmation for all 5 write capabilities (comment, transition, reassign, create, link) behind one config flag, but triage-flow itself only ever uses comment/create/link — transition and reassign are explicitly out of scope for this flow. Any future caller of jira-write under the same flag silently inherits unattended transition/reassign, which is broader than this build's own justification supports.
• jira-write/SKILL.md's body states "never hardcode a specific tool name," then itself says "Jira account" / "a live, shared Jira ticket" twice in <core_concepts> and once in <identity_note> — the vendor-neutral framing leaks into the main skill file instead of staying confined to references/jira-write-vendor-binding.md, unlike the data-collection skill it's modeled on.

Caveats:

• Design is otherwise coherent: the phased tick model, two-state resumability for the irreversible create-then-link write, and comment-ID-based (not author-based) idempotency are all well-reasoned and clearly documented, with the POC-scope shortcuts flagged inline rather than hidden.
• .mcp.json, agents/jira-mcp-auth-header.sh, and .gitignore changes were checked; no secrets are committed, and the auth helper correctly reads from an untracked sibling file or JIRA_API_TOKEN.

Suggestions:

• Reword the data-collection internal-file references to intent-level ("USE SKILL data-collection...") across the three files listed above.
• Refresh all subagent_required_model lists to the current R3 canonical model IDs.
• Trim both over-length frontmatter descriptions to fit the schema's token budget.
• Either scope the POC-SCOPE-OVERRIDE to only the write capabilities this flow actually uses (comment/create/link), or explicitly document in the override note that transition/reassign inherit the same bypass for any future caller.

Questions:

• Is the plan to scope confirmation_gate_override per-operation in a follow-up, or is a skill-wide bypass the intended long-term shape once this moves past POC?

Automated triage by Rosetta agent

[sergepr]

Pushed a follow-up commit (211efec) addressing the automated Rosetta triage review:

• Reworded the 3 direct issue-vendor-binding.md references to intent-level phrasing (USE SKILL data-collection...), per pa-hardening's cross-skill isolation rule.
• Refreshed all 6 phase files' subagent_required_model lists from stale R2-era IDs to the current R3 canonical sets (matched to requirements-authoring-flow.md and init-workspace-flow.md's equivalent roles).
• Trimmed both over-length frontmatter descriptions to schema budget.
• Documented that jira-write's POC-SCOPE-OVERRIDE is skill-wide, not per-operation — transition/reassign inherit the bypass even though this build only uses comment/create/link.

Left open for review, since they need a judgment call rather than a mechanical fix:

• Whether the dangerous-actions "steps 1-4 still run" claim is actually licensed by that skill's atomic 5-step process.
• The vendor-neutral-framing leak into jira-write/SKILL.md's core_concepts (mentions "Jira account" directly instead of staying capability-generic).

[sergepr]

Pushed a second follow-up commit (ddf7fad) closing out the remaining 2 findings from the automated Rosetta triage review that 211efec left open for review:

• core_concepts and dangerous_actions_gate said "Jira account" / "Jira ticket" despite this file's own stated principle one paragraph earlier ("never hardcode a specific tool name"). Reworded both to "Issue Tracker", matching data-collection's convention (the skill this one is modeled on) and jira-write-vendor-binding.md's own capability-generic prose. Note: the skill's name/directory/file paths stay Jira-specific on purpose — this build is a Jira-only POC, consistent with jira-triage.config.json, jira-mcp-auth-header.sh, and the jira-service-account MCP registration. Only the two body-prose mentions were the actual inconsistency.
• The POC-SCOPE-OVERRIDE paragraph claimed "the content-level blast-radius check (steps 1-4) still runs," implying dangerous-actions licenses partial application of its own 5-step process — it doesn't (it defines one linear process, and this is the only place in instructions/r3 that overrides its step 5 / hitl's "dangerous actions ALWAYS require explicit approval" rule). Reworded so the content-level check is framed as this build's own choice to keep, not something dangerous-actions sanctions running standalone.

On the underlying design question that wording change doesn't resolve — why unattended writes to a live ticket at all: triage-flow's whole mechanism is the comment round-trip — phase 4 posts Open Questions derived from the elicitation phase's Requirements.md, and the requester waits for the ticket reporter's reply in a comment, not an interactive prompt in this session. Gating every one of those on a human confirmation here would defeat the flow's actual design (a tick-based, asynchronous loop meant to run unattended between CI dispatches), not just add friction to it. The bypass is also narrower than it looks: scoped to comment/create/link only (transition/reassign are unused by this build, explicitly out of scope), every write is manually revertible except create issue (which instead carries its own extra duplicate-prevention-evidence requirement before it's allowed to fire), and the actual human-in-the-loop gate for this flow's output sits downstream, in harness-intake's own PR review — not inside Jira ticket state.

All 6 findings from the automated review are now addressed across 211efec + ddf7fad.

[isolomatov-gd]

Maybe you can intro what and why this flow was implemented?

1. There is no skill included you mentioned.
2. Why is it this big? Are we explaining to AI something it already knows?
3. Did you check if you could just extend https://github.com/griddynamics/rosetta/blob/main/instructions/r3/core/skills/backlog/SKILL.md ?
4. What was the purpose of {"op": "add_comment", "target_issue_key": "<key>", "payload": {"body": "<composed body>"}, "composed_at": "<ISO8601>"}  and <artifacts_dir>/<TICKET-KEY>/jira-writes/<NNN>-add_comment.json, why can't it show to user for approval and then write directly?
5. Pls also replace jira and similar tech with technology agnostic keyword issue tracker, etc.
6. This looks like a regular skill, not the workflow, especially if we talk about triaging a single story.