# Test Design: Story 2.1 - Create & List Shared Steps

**Date:** 2026-01-17
**Author:** Antigravity (Agent)
**Status:** Draft
**Epic:** 2 (Shared Steps & Reusability)

---

## Executive Summary

**Scope:** Epic-Level (Targeted Story 2.1 validation)
**Goal:** Verify reliability and agent-usability of Shared Step management tools.

**Risk Summary:**

- Total risks identified: 3
- High-priority risks (≥6): 1
- Critical categories: BUS (Agent Experience)

**Coverage Summary:**

- P0 scenarios: 2 (4 hours)
- P1 scenarios: 2 (2 hours)
- P2/P3 scenarios: 3 (1.5 hours)
- **Total effort:** 7.5 hours (~1 day)

---

## Risk Assessment

### High-Priority Risks (Score ≥6)

| Risk ID | Category | Description | Probability | Impact | Score | Mitigation | Owner | Timeline |
| ------- | -------- | ----------- | ----------- | ------ | ----- | ---------- | ----- | -------- |
| R-2.1-1 | BUS | **Agent Hallucination/Usage Failure**: AI agents unable to correctly interpret or use the shared step tools due to unclear documentation or complex schema, leading to feature abandonment. | 2 (Possible) | 3 (Critical) | 6 | Implement "LLM-Optimized" docstrings with few-shot examples (AC #3). Verify via Agent-Zero testing. | Dev/PM | Story 2.1 |

### Medium-Priority Risks (Score 3-4)

| Risk ID | Category | Description | Probability | Impact | Score | Mitigation | Owner |
| ------- | -------- | ----------- | ----------- | ------ | ----- | ---------- | ----- |
| R-2.1-2 | PERF | **List Scalability**: Listing shared steps in a large project (>1000) causes timeouts or context window overflow for agents. | 2 (Possible) | 2 (Degraded) | 4 | Implement pagination in `list_shared_steps` (Task 1.5). Limit default page size. | Dev |

### Low-Priority Risks (Score 1-2)

| Risk ID | Category | Description | Probability | Impact | Score | Action |
| ------- | -------- | ----------- | ----------- | ------ | ----- | ------ |
| R-2.1-3 | DATA | **Invalid Schema**: Creating shared steps with malformed step objects (missing action/expected) corrupts library. | 1 (Unlikely) | 2 (Degraded) | 2 | Strict Pydantic validation on input tools. | Monitor |

---

## Test Coverage Plan

### P0 (Critical) - Run on every commit

**Criteria**: Blocks core journey (Agent Usage) + High risk (≥6)

| Requirement | Test Level | Risk Link | Test Count | Owner | Notes |
| ----------- | ---------- | --------- | ---------- | ----- | ----- |
| AC #1 (Create) | E2E | R-2.1-1 | 1 | QA | Verify agent can successfully create a valid shared step. |
| AC #2 (List) | E2E | R-2.1-1 | 1 | QA | Verify agent can list and find the created step. |

**Total P0**: 2 tests, 4.0 hours

### P1 (High) - Run on PR to main

**Criteria**: Important features + Medium risk

| Requirement | Test Level | Risk Link | Test Count | Owner | Notes |
| ----------- | ---------- | --------- | ---------- | ----- | ----- |
| AC #1 (Create) | API/Int | R-2.1-3 | 1 | Dev | Validate error on missing `action/expected` fields. |
| AC #3 (Docs) | Unit | R-2.1-1 | 1 | Dev | Verify tool definitions contain required docstrings. |

**Total P1**: 2 tests, 2.0 hours

### P2 (Medium) - Run nightly

**Criteria**: Secondary features + Scalability

| Requirement | Test Level | Risk Link | Test Count | Owner | Notes |
| ----------- | ---------- | --------- | ---------- | ----- | ----- |
| AC #2 (List) | API/Int | R-2.1-2 | 1 | Dev | Verify pagination params (page, size) work. |
| AC #1 (Create) | Unit | - | 1 | Dev | Verify SharedStepService logic mapping. |
| AC #2 (List) | Unit | - | 1 | Dev | Verify service list logic. |

**Total P2**: 3 tests, 1.5 hours

---

## Execution Order

### Smoke Tests (<5 min)

- [ ] `test_create_shared_step_e2e` (Verify creation)
- [ ] `test_list_shared_steps_e2e` (Verify listing)

### P0 Tests (<10 min)

- [ ] Same as Smoke Tests (Core flow is the only P0 here)

### P1 Tests (<30 min)

- [ ] `test_create_shared_step_validation` (API)
- [ ] `test_tool_definitions` (Unit)

### P2 Tests (<60 min)

- [ ] `test_list_pagination` (API)
- [ ] `test_service_unit_tests` (Unit)

---

## Quality Gate Criteria

### Pass/Fail Thresholds

- **P0 pass rate**: 100%
- **P1 pass rate**: 100% (Strict Agent Reliability)
- **High-risk mitigations**: Docstrings MUST be verified.

### Non-Negotiable Requirements

- [ ] All E2E tests pass in Sandbox.
- [ ] Pydantic models strictly enforce `SharedStepCreate` schema.

---

## Appendix

### Related Documents

- Story: [2-1-create-and-list-shared-steps.md](file:///Users/anmaro/Code/personal/github.com/lucius-mcp/specs/implementation-artifacts/2-1-create-and-list-shared-steps.md)
- PRD: [prd.md](file:///Users/anmaro/Code/personal/github.com/lucius-mcp/specs/prd.md)

**Generated by**: BMad TEA Agent - Test Architect Module
**Workflow**: `_bmad/bmm/testarch/test-design`
