agentic-workflow-issue-factory

name	agentic-workflow-issue-factory
description	Use when converting agentic AI/RAG architecture into GitHub issues, implementation specs, acceptance criteria, rollout notes, and checklists for simpler coding agents.
version	1.0.0
author	Hermes Agent
license	MIT
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["agents","github-issues","specs","acceptance-criteria","product-engineering"],"related_skills":["principal-ai-architect","github-issues","production-rag-architecture","rag-evaluation-observability"]}}

Agentic Workflow Issue Factory

Overview

Use this skill to turn architecture into implementation-ready GitHub issues for coding agents. The output should be scoped, testable, and explicit about business goals, architecture context, files likely to change, non-goals, acceptance criteria, verification commands, observability, and rollout/rollback.

When to Use

Use when asked to:

• create GitHub issues for AI/RAG/agent work
• break a roadmap into shippable tasks
• document acceptance criteria for coding agents
• convert ADRs/design docs into build tasks
• prepare specs for implementation agents
• add visuals or reasoning to issue bodies

Issue Slicing Rule

A good issue should fit 1-3 focused coding sessions. If it cannot, split it by pipeline layer or user-visible behavior.

Good slices:

• Add metadata validation for ingestion manifests.
• Add Recall@k breakdown by namespace.
• Add router logging for selected namespace and model tier.
• Add no-answer eval cases for hallucination resistance.
• Add cost-per-request metric to AI traces.
• Add hybrid retrieval eval slice for acronym-heavy queries.

Bad slices:

• Build all observability.
• Rewrite the agent framework.
• Make RAG better.
• Add enterprise integrations.

Issue Generation Workflow

1. Identify the business goal.
2. Link architecture context: SOUL.md, ADR, design note, or roadmap phase.
3. State the problem in production terms: quality, latency, cost, reliability, adoption, or risk.
4. Define the smallest implementation path.
5. Name likely files/modules only after inspecting the repo when possible.
6. Add explicit non-goals.
7. Add acceptance criteria that can be checked by tests/evals/traces.
8. Add verification commands.
9. Add rollout and rollback notes if behavior changes.
10. Add diagrams for multi-component workflows.

Acceptance Criteria Patterns

Functional:

• User-visible behavior is implemented
• Inputs and outputs are typed or schema-validated
• Error/fallback behavior is defined

Evaluation:

• Golden dataset cases added or updated
• Retrieval/generation/agent metrics reported
• Regression threshold passes

Observability:

• Trace fields emitted
• Cost, token, latency, and quality dimensions captured
• Failure mode is structured

Operations:

• Rollout path documented
• Rollback path documented
• No secrets or PII are logged

Common Pitfalls

1. No business goal. Coding agents need to know why the work matters.
2. Too large. Split by pipeline layer or metric.
3. Missing non-goals. Agents will otherwise overbuild.
4. Acceptance criteria that require human vibes. Prefer metrics, commands, and trace fields.
5. No eval linkage. AI changes must prove quality did not regress.
6. No rollback plan. Production AI changes need reversibility.

Verification Checklist

• Issue title is action-oriented and scoped
• Business goal is explicit
• Architecture context is linked or summarized
• Problem statement is concrete
• Proposed approach is minimal
• Files likely to change are listed when known
• Non-goals are present
• Acceptance criteria are testable
• Verification commands are present
• Observability and eval expectations are present
• Rollout/rollback notes are present when needed