Apply suggestions from code review

Co-authored-by: AlexLgn <[email protected]>

Author: TriplEight

.github/ISSUE_TEMPLATE/case.md

@@ -7,58 +7,79 @@ assignees: ''
 
 ---
 
-System Context: [Which system/subsystem this case addresses and its position in the larger system architecture]
+[Case writing rules:
+- Product Focus: Define agent value and experience, not technical implementation
+- Agent Priority: List agents by % importance with Human/System distinction (even if similar to other cases)  
+- Target System Clarity: Explicitly identify target system and distinguish from consumer/dependency systems
+- System Boundaries: Explicitly state what's included/excluded from this case
+- Basic English: Write for non-native speakers, avoid complex technical terms
+- Scope Limit: Target 3-6 month achievable milestones only
+- Agent-Driven: Focus on agent behavior and adoption, not system performance]
 
-## Problem Statement
-[Describe the problem from the stakeholder's perspective. What current state needs to change and why? Leave technical details for `hypoteses`.]
+## Target System
+
+[Which system this case addresses and its position in the larger system architecture]
 
-### Current State
+## Problem Statement
+[Describe the agent/business problem this case solves. What current state needs to change and why? Focus on WHAT agents need and WHY it matters. Leave technical details for  `hypoteses` of experiments.]
 
-[What exists today]
+### Current Agent Experience
 
-### Desired State
+[What agents experience today that needs improvement]
 
-[What we want to achieve]
+### Desired Agent Experience
 
-### Gap
+[What agents should be able to do after this case is complete]
 
-[What's missing or broken]
 
 ## Value Proposition
 
-[Clearly articulate the value this case will deliver to the organization and stakeholders]
+[Clear business/agent value this case provides]
 
-## Stakeholder Analysis
+## Agent Analysis
 
-[Map all stakeholders with their roles, interests, and influence on the system]
+[Map all agents (human and system) by priority with percentages. Focus on WHO/WHAT will interact with or benefit from the Target System.]
+**Agent Priority Overview**: [e.g., "Primary: 60% Developers, Secondary: 30% Monitoring Systems, Minimal: 10% End Users"]
+[Optional: Include not only percentages but also evaluation/justification for why these priorities make sense for this case]
 
-**[Actor 1]**
-Role:
-Interest/Goal:
-Influence Level: [High/Medium/Low]
-[How they measure success]
+### [Primary Agent Name] ([X%] - Primary)
+- **Agent Type**: [Human Agent: role/persona] OR [System Agent: system type/function]
+- **Current Pain Points**: [What problems they have today with existing systems]
+- **Desired Outcomes**: [What success looks like for them]
+- **Agent Journey**: [Action] → [Action] → [Successful Outcome]
+- **Success Metrics**: [How they measure success - can include system metrics for System Agents]
+- **Integration Requirements**: [For System Agents: APIs, data formats, protocols needed]
 
-**[Actor 2]**
-Role:
-Interest/Goal:
-Influence Level: [High/Medium/Low]
-[How they measure success]
+### [Secondary Agent Name] ([Y%] - Secondary)
+[Same structure as above]
 
-## Expected Behaviors & Acceptance
-[BDD scenarios that define both the expected system behavior and the acceptance criteria]
+[Continue pattern for all Agents, ordered by priority]
 
-### Primary Happy Path
+## Expected Agent Experience & Acceptance
+[BDD scenarios that define both the Target System behavior and the acceptance criteria. Describe what agents will experience, NOT how the Target System works internally. Focus on acceptance testing, not repeating desired outcomes already listed in Agent Analysis. Validation priorities derive from Agent Priority Overview above - no separate priority statement needed here]
 
-Given [Initial system state and context]
-When [Stakeholder performs action]
-Then [Expected system response and outcome]
-And [Additional expected behaviors]
+### Agent Acceptance Scenarios
+**Scenario 1: [Primary Happy Path for Human Agent]**
+- Given [agent context/starting point]
+- When [agent performs action]
+- Then [agent experiences result]
+- And [additional agent benefit]
 
 **Acceptance Criteria:**
+[It would be preferable if non-developers can verify this work in 5-10 minutes]
 - [ ] [Specific measurable criterion for this scenario]
 - [ ] [Performance/quality requirement for this behavior]
 
-### Alternative Path
+**Scenario 2: [Primary Happy Path for System Agent]**
+- Given [system agent needs specific data/functionality]
+- When [system agent makes API call/integration request]
+- Then [target system provides required response/data]
+- And [system agent can successfully complete its function]
+
+**Acceptance Criteria:**
+[How to verify system agent integration works, e.g. API tests, data format checks]
+
+**Scenario 3: [Alternative Path]**
 
 Given [Different initial conditions]
 When [Alternative stakeholder action]
@@ -67,7 +88,7 @@ Then [Expected alternative response]
 **Acceptance Criteria:**
 - [ ] [Specific measurable criterion for this scenario]
 
-### Error/Edge Case:
+**Scenario 4: [Error/Edge Case Handling]**
 
 Given [Error conditions]
 When [Action that triggers error]
@@ -78,11 +99,11 @@ Then [Expected error handling behavior]
 
 ## System Context & Boundaries
 
-### System Scope
+### Target System Scope
 
-In Scope: [What the system will do and boundaries included]
+In Scope: [What the Target System will do and boundaries included]
 Out of Scope: [What explicitly won't be addressed]
-Interfaces: [External systems, data flows, and dependencies]
+Interfaces: [External systems (consumer systems, dependency systems, peer/interacting systems), data flows, and dependencies.]
 
 ### Quality Attributes
 
@@ -109,10 +130,7 @@ Owner: [Responsible person]
 ## Decision Log
 [Record key architectural and design decisions]
 
-Date: [Date]
-Decision: [Decision made]
-Rationale: [Why this decision]
-Impact: [What it affects]
+[Date] - [Decision] - [Rationale] - [Impact on agents]
 Status: [Active/Superseded]
 
 ## Learning Outcomes
@@ -128,3 +146,15 @@ Unexpected discoveries:
 
 Process improvements:
 Technical approach changes:
+
+
+[
+Final Checklist Before Submitting:
+- [ ] Does this describe Agent value, not technical implementation?
+- [ ] Are agents prioritized with clear percentages and Human/System distinction?
+- [ ] Is the Target System clearly identified and distinguished from consumer/dependency systems?
+- [ ] Are system boundaries clearly defined?
+- [ ] Is the language simple enough for non-native speakers?
+- [ ] Is the scope limited to 3-6 months of achievable work?
+- [ ] Do scenarios focus on agent behavior, not system performance?
+]