edit templates after review

Author: AlexLgn

.github/ISSUE_TEMPLATE/case.md

@@ -8,83 +8,52 @@ assignees: ''
 
 [Case Brief writing rules:
 - Product Focus: Define agent value and experience, not technical implementation
-- Problem Analysis: Lives in Case Product Specification - Brief references Spec for context
 - Agent Priority: List agents by % importance with Human/System distinction (even if similar to other cases)
 - Basic English: Write for non-native speakers, avoid complex technical terms
 - Stakeholder Language: This brief is for business/product stakeholders
 - Minimal Content: Engineers need context to understand "what" and "why", not extensive product analysis
 - System Boundaries: Explicitly state what's included/excluded
 - Link to Details: Extended analysis lives in Coda, link from here
-- Scenario-Driven: Focus on agent behavior and acceptance, not system performance
-- Scope Limit: Target 3-6 month achievable milestones
-- Experiment Mapping: Link acceptance criteria to implementing experiments
+- Acceptance Focus: Define observable outcomes that stakeholders can verify, not technical validation procedures
+- Scope Limit: Target achievable work within project constraints (don't boil the ocean)
+- DRY: Reference specifications, don't copy content
 - Metrics Cascade: Case Product Specification defines product success metrics → Case Brief translates to verifiable acceptance criteria → Experiments validate technical implementation
-- Link Don't Duplicate: Reference specifications, don't copy content]
+- Dependencies: For complex dependency chains, create visual diagrams instead of listing in text
+- ADRs: Technical decisions are documented in Architecture Decision Records (ADRs) within experiments, not in cases]
 
 ## Engineered System
 
 [Which specific system/subsystem are we building and what is its position in the larger system architecture?]
 
-*For detailed system context, complete problem analysis including current/desired agent experience, see: [Case Product Specification](link-to-coda)*
-
 ## Agent Priority Overview
 
 [High-level stakeholder priorities with percentages. Detailed analysis in Case Product Specification in Coda.]
 
 **Priority Distribution:** [e.g., "Primary: 60% Developers; Secondary: 30% System Integrators; Minimal: 10% End Users"]
 
 **Rationale:** *Optional* [1-2 sentence justification for these priorities]
-
-*For detailed agent analysis with agent journeys and integration requirements, see: [Case Product Specification](link-to-coda)*
-
 ## Expected Agent Experience & Acceptance
 
-[Define scenarios the Engineered System must handle and acceptance criteria. Focus on observable outcomes, not internal system operations.]
-
-*Note: Link acceptance criteria to implementing experiments during experiment planning phase.*
-
-### Agent Acceptance Scenarios
+[Brief paragraph: What agents will be able to do after this case is complete. Focus on observable outcomes and agent value.]
 
-**Scenario 1: [Primary Scenario for Primary Agent]**
-- Given [detailed initial conditions]
-- When [agent performs action]
-- Then [agent experiences result]
-- And [additional agent benefit]
+### Acceptance Criteria
 
-**Acceptance Criteria:**
-[Each criterion should be demonstrable within 5-10 minutes by non-developers or through developer demo. Validation methods: Observable (UI/logs/behavior), Measurable (counted/timed), Testable (test scripts), User-Validated (actual users)]
+[Group criteria by agent type. Keep criteria simple and observable - verifiable by stakeholders in 5-10 minutes. Detailed validation procedures belong in Acceptance Experiment, not here. No experiment links - checkboxes show validation status when marked in stakeholder meetings.]
 
-- [ ] [Specific criterion] → **Experiment**: [Link #XXX when available or TBD]
-  - *Validation: [How to verify - e.g., "Dashboard shows metric within target"]*
-- [ ] [Performance/quality requirement] → **Experiment**: [Link #XXX when available or TBD]
-  - *Validation: [Verification method]*
+**For [Primary Agent Type]:**
+- [ ] [Observable outcome or capability]
+- [ ] [Measurable result or behavior]
+- [ ] [Demonstrable functionality]
 
-**Scenario 2: [Secondary Scenario - Success path for Secondary Agent]**
-- Given [different initial conditions]
-- When [alternative agent action]
-- Then [expected alternative outcome]
+**For [Secondary Agent Type]:**
+- [ ] [Observable outcome or capability]
+- [ ] [Measurable result or behavior]
 
-**Acceptance Criteria:**
-- [ ] [Specific criterion] → **Experiment**: [Link #XXX when available or TBD]
-  - *Validation: [Verification method]*
+**For [Tertiary Agent Type]:**
+- [ ] [Observable outcome or capability]
+- [ ] [Measurable result or behavior]
 
-**Scenario 3: [Alternative Scenario - Different approach or edge case]**
-- Given [edge case conditions]
-- When [action that triggers alternative path]
-- Then [expected handling]
-
-**Acceptance Criteria:**
-- [ ] [Specific criterion] → **Experiment**: [Link #XXX when available or TBD]
-  - *Validation: [Verification method]*
-
-**Scenario 4: [Error Scenario - Failure case and recovery]**
-- Given [error conditions]
-- When [action that triggers error]
-- Then [expected error handling and recovery]
-
-**Acceptance Criteria:**
-- [ ] [Error handling criterion] → **Experiment**: [Link #XXX when available or TBD]
-  - *Validation: [Verification method]*
+[Continue for all relevant agent types. Focus on WHAT agents experience, not HOW the system works internally.]
 
 ## Scope Summary
 
@@ -94,45 +63,19 @@ assignees: ''
 
 **Out of Scope:** [What explicitly will not be addressed - link to other cases handling these]
 
-*For detailed interfaces and integration points, see: [Case Architecture Specification](link-to-arch-doc)*
-
-## Critical Dependencies & Blockers
-
-**Blocking This Case:**
-- [Case/System #X]: [What must complete before we can proceed]
+## References & Links *Optional*
 
-**This Case Blocks:**
-- [Case/System #Y]: [What depends on this case's completion]
-
-**Bottlenecks** (Resource constraints):
-- [Resource constraint] - Impact: [Description]
-
-**External Blockers** (Third-party dependencies):
-- [Third-party dependency] - Expected resolution: [Timeline]
-
-**Critical Path Items:**
-- [Dependency with resolution date]
-- [Risk requiring immediate attention]
-
-*For complete dependency analysis and technical interfaces, see: [Case Product Specification](link-to-coda) and [Case Architecture Specification](link-to-arch-doc)*
-
-## Decision Log
-
-[Enumeration of related ADRs - decisions themselves live in ADR documents]
-
-- [Date] - ADR #[XXXX] - [Case decomposition decision] - [Link to ADR]
-  Status: [Active/Superseded by ADR #[XXXX]]
-- [Date] - ADR #[XXXX] - [Brief description] - [Link to ADR]
-  Status: [Active/Superseded by ADR #[XXXX]]
-
-## References & Links
+[Include this section when you need to reference external context, related work, or technical background. Delete if not applicable.]
 
 **Full Case Details:**
 - [Case Product Specification](link-to-coda) - Extended product analysis, detailed agent journeys, business context
 
 **Related Architecture:**
 - [Case Architecture Specification](link-to-arch-doc) - Technical architecture, interfaces, integration points
 
+**Related Cases:**
+- [Case #XXX]: [Brief description of relationship]
+
 ## Learning Outcomes
 
 [To be filled during and after case completion]
@@ -150,22 +93,22 @@ assignees: ''
 
 [People who should review and acknowledge understanding of this experiment]
 
-- [ ] [Person 1]
-- [ ] [Person 2]
-- [ ] [Person 3]
+- [ ] @github-handle-1
+- [ ] @github-handle-2
+- [ ] @github-handle-3
 
 *Note: Check your name after reading and understanding this case to confirm awareness and reduce communication overhead.*
 
 ---
 
-**Final Checklist Before Submitting:**
+[Note: Delete this checklist section once the case is submitted]
+
+[Final Checklist Before Submitting:
 - [ ] Does this describe agent value, not technical implementation?
-- [ ] Is problem analysis referenced (not duplicated) from Case Product Specification?
 - [ ] Is Agent Priority Overview high-level with justification?
-- [ ] Are acceptance criteria clear and verifiable?
-- [ ] Do scenarios use correct terminology (Primary/Secondary/Alternative/Error)?
-- [ ] Is scope limited to 3-6 months of achievable work?
-- [ ] Are only critical dependencies and blockers listed?
+- [ ] Are acceptance criteria simple, grouped by agent?
+- [ ] Are acceptance criteria verifiable by stakeholders (observable outcomes)? Are we focused on delivering demonstrable outcomes?
+- [ ] Is scope limited to achievable work within project constraints?
+- [ ] Are we solving the immediate problem, not building the ultimate solution (don't boil the ocean)?
 - [ ] Are links to Case Product Specification and Architecture docs present?
-- [ ] Are experiment links marked as TBD where not yet planned?
-- [ ] Is Review & Acknowledgment section complete?
+- [ ] Is Review & Acknowledgment section complete with GitHub handles?]

.github/ISSUE_TEMPLATE/experiment.md

@@ -12,28 +12,22 @@ assignees: ''
 - Engineer Freedom: Choose verification approach that fits hypothesis
 - Run Fast: Code may be thrown away if hypothesis fails
 - Technical Focus: Success criteria are technical, not product/user outcomes. Product criteria live in Case Brief
-- Link, Don't Copy: Reference Case Brief, Architecture docs - don't duplicate]
+- DRY: Reference Case Brief, Architecture docs - don't duplicate
+- Dependencies: Use GitHub issue status ('Blocked') and comments for blockers. Don't list dependencies in the experiment description - that's project management, not technical specification
+- ADRs Optional: Create Architecture Decision Records (ADRs) only when decisions affect other teams or have long-term consequences. Engineers have freedom for local implementation choices]
 
-## Experiment Type & Hypothesis
+## Experiment Hypothesis
 
-**Type:** [Implementation / Research / Analysis / Proof-of-Concept]
+**Hypothesis:** [Technical approach or assumption we're testing]
 
-**What we believe:** [Technical approach or assumption we're testing]
+**Rationale:** [Optional - brief rationale if not obvious]
 
-**Expected outcome:** [Measurable technical result we expect]
+## Out of Scope
 
-**How we'll verify:** [Brief verification approach - detailed in Success Criteria below, expand in Verification Approach if non-standard]
+[What's explicitly not included - prevents scope creep]
 
-## Implementation Scope
-
-[What we're building/testing in 1-2 sentences - keep brief and specific]
-
-**In Scope:**
-- [Specific technical work included]
-- [Component/feature being implemented]
-
-**Out of Scope:**
-- [What's explicitly not included - link to other experiments if applicable]
+- [Exclusion with brief reason]
+- [Link to other experiment handling this if applicable]
 
 ## Technical Approach *Optional*
 
@@ -43,7 +37,7 @@ assignees: ''
 [Key technical decisions or approach details]
 
 **Technology Stack:** [If relevant to hypothesis]
-- [Technology/tool/Library] - [Optional - brief reason. Detailed "why" in ADRs if architectural decision]
+- [Technology/Tool/Library] - [Optional - brief reason. Detailed "why" in ADRs if architectural decision]
 
 ## Engineered System Context *Optional*
 
@@ -66,23 +60,9 @@ assignees: ''
 
 *For complete integration architecture, see: [Architecture Documentation](link)*
 
-**Critical Path:**
-
-*Impediments* (Active obstacles):
-- [Active obstacle preventing work] - Status: [Active/Resolved]
-
-*Bottlenecks* (Resource constraints):
-- [Resource constraint slowing progress]
-
-*External Blockers* (Third-party dependencies):
-- [Dependency causing delays] - Expected resolution: [Timeline]
-
-*Blocking this experiment:*
-- [Experiment/System #X must complete first]
-
 ## Outcomes
 
-[Checkbox list - when all checked, experiment is ready to close]
+[Checkbox list of concrete deliverables - when all checked, experiment is complete. If needed create categories that match your work. The following provides examples of the categories and outcomes]
 
 **Code/Artifacts:**
 - [ ] [Specific code module/component committed to branch X]
@@ -132,19 +112,9 @@ assignees: ''
 **Standard approach assumed:** Code review + linter + basic testing to verify hypothesis
 
 **Special verification for this experiment:**
-- [Document only non-standard verification needs, e.g.:
-  - Load testing with specific parameters
-  - Security review due to sensitive operations
-  - Integration testing with specific external system]
+- [Document only non-standard verification needs, e.g., load testing, security audit, manual testing protocol, etc.]
 
-## Resources & Timeline
-
-**Team:**
-- [Role/Person] - [Time commitment]
-
-**Timeline:** [Estimated duration for experiment]
-
-## Decision Log
+## Decision Log *Optional*
 
 [Enumeration of related ADRs - decisions themselves live in ADR documents]
 
@@ -153,19 +123,19 @@ assignees: ''
 - [Date] - ADR #[XXXX] - [Brief description] - [Link to ADR]
   Status: [Active/Superseded by ADR #[XXXX]]
 
-## References & Links
-
-**Case Brief:** [Link] - See acceptance criteria for product context
+## References & Links *Optional*
 
-**Full Case Details:**
-- [Case Product Specification](link-to-coda) - Extended product analysis, detailed agent journeys, business context
+[Include this section when you need to reference external context, related work, or technical background. Delete if not applicable.]
 
 **Architecture Docs:** [Link if exists] - Technical architecture and design decisions
 
-**Additional Resources:** [Optional]
-- [Tool documentation]
-- [Best practices guide]
-- [Research paper]
+**Technical Documentation:**
+- [Architecture docs, API specs, standards]
+
+**External Resources:**
+- [Research papers, library docs, similar implementations]
+
+**Additional Resources:**
 - [Meeting notes]
 - [Related experiments]
 
@@ -206,21 +176,20 @@ assignees: ''
 
 [People who should review and acknowledge understanding of this experiment]
 
-- [ ] [Person 1]
-- [ ] [Person 2]
-- [ ] [Person 3]
+- [ ] @github-handle-1
+- [ ] @github-handle-2
+- [ ] @github-handle-3
 
 *Note: Check your name after reading and understanding this case to confirm awareness and reduce communication overhead.*
 
 ---
 
-**Final Checklist Before Submitting:**
+[Note: Delete this checklist section once the experiment is submitted]
+
+[Final Checklist Before Submitting:
 - [ ] Is hypothesis clear and testable?
-- [ ] Are success criteria measurable and technical (not product-focused)?
-- [ ] Is scope limited and specific to this experiment?
-- [ ] Are links to Case Brief and Architecture docs present?
-- [ ] Are only critical dependencies listed?
-- [ ] Is verification approach appropriate (standard or documented special needs)?
-- [ ] Is this lightweight enough for experimental approach (not production feature development)?
-- [ ] Does Decision Log enumerate relevant ADRs?
-- [ ] Are Outcomes specific and actionable?
+- [ ] Are outcomes concrete and verifiable?
+- [ ] Are success criteria specific with measurable thresholds?
+- [ ] Is scope limited (what's excluded is clear)?
+- [ ] Is this focused on validating one specific technical approach?
+- [ ] Are we running fast to test the hypothesis, not building the perfect solution?]