Concrete artifacts

[co0p]

Below are 5 artifacts per phase, drawing from XP and complementary practices (Lean, DDD, BDD, ADRs, Shape Up, Wardley, etc.). Each artifact includes a suitability rating (1–5), pros, and cons to help you choose pragmatically. Aim to pick 2–3 per phase based on context, not all five.

Phase 1: User story / Feature (intent and scope)

1. User Story (XP)

• Suitability: 5
• Pros: Simple, aligns with value; good for prioritization; ubiquitous format.
• Cons: Can be vague; benefits often hand-wavy; encourages shallow analysis if not paired with examples.

2. Acceptance Criteria in Gherkin (BDD)

• Suitability: 5
• Pros: Testable, executable; clear shared language across roles; anchors downstream tests.
• Cons: Requires discipline to avoid over-specification; can be verbose for UI-heavy features.

3. Example Mapping (BDD discovery)

• Suitability: 4
• Pros: Fast alignment tool; uncovers rules, examples, and questions; reduces ambiguity.
• Cons: Output is lightweight; needs facilitation; can be hard to persist without structure.

4. Outcome Hypothesis (Lean/Impact Mapping)

• Suitability: 4
• Pros: Explicit value targets and measures; focuses on outcomes not outputs.
• Cons: Measurement can be hard; risks idealism if metrics are not feasible to collect.

5. Job Story (JTBD)

• Suitability: 3
• Pros: Captures context and motivation better than User Story; good for UX-heavy work.
• Cons: Less testable by itself; can drift away from system constraints; needs translation to acceptance criteria.

Phase 2: Design (responsibilities, contracts, decisions)

1. CRC Cards (XP)

• Suitability: 4
• Pros: Keeps design simple; clarifies responsibilities and collaborations.
• Cons: Abstract for non-OOP systems; can miss cross-cutting concerns or data invariants.

2. Sequence Diagram/Sketch (UML-lite)

• Suitability: 5
• Pros: Visualizes interactions; surfaces error handling and ordering; great for API/integration.
• Cons: Can go stale; heavy tooling if formal UML; needs text alternatives for code reviews.

3. API Contract with Examples (OpenAPI/JSON)

• Suitability: 5
• Pros: Concrete; directly drives tests and mocks; clarifies error shapes and invariants.
• Cons: Temptation to over-specify; may ignore non-API parts of the system.

4. Architecture Decision Record (ADR)

• Suitability: 5
• Pros: Captures context, alternatives, and consequences; excellent for auditability and onboarding.
• Cons: Overhead if abused; needs curation to avoid noise; decisions can be premature.

5. Context/Container Diagram (C4 Model)

• Suitability: 4
• Pros: Establishes boundaries, external dependencies, and deployment view.
• Cons: Might be overkill for small features; risks big-design-up-front if too detailed.

Phase 3: Task breakdown / Implementation (thin slices, test-first)

1. Vertical Slice Plan (Shape Up/XP thin slices)

• Suitability: 5
• Pros: Delivers end-to-end increments; demoable; reduces integration risk.
• Cons: Requires careful scoping; can feel slower at first vs. layer-first.

2. Test Skeletons (Acceptance + Unit)

• Suitability: 5
• Pros: Enforces test-first; clarifies API and behavior; enables safe refactoring.
• Cons: Initial friction; poorly named tests degrade readability; needs CI discipline.

3. Interface/Port Stubs (Hexagonal/Ports & Adapters)

• Suitability: 4
• Pros: Decouples core from infrastructure; supports swapping implementations and testing.
• Cons: Extra indirection if overused; risks premature abstraction without clear need.

4. Task Board with Explicit DoD and Risks (Kanban)

• Suitability: 4
• Pros: Visualizes flow; makes risks and done criteria explicit; supports WIP limits.
• Cons: Adds process overhead; can devolve into status tracking without value focus.

5. Deployment/Feature Flag Plan (Release strategy)

• Suitability: 4
• Pros: Enables safe rollout, canarying, and phased enablement; supports ops collaboration.
• Cons: Adds config complexity; needs governance to avoid flag debt.

Phase 4: Improvement / Refactoring (design health)

1. Refactoring Log (Change, Motivation, Tests, Rollback)

• Suitability: 5
• Pros: Documents rationale; links to tests; helps code review and knowledge transfer.
• Cons: Requires discipline; can become repetitive; must stay short to be useful.

2. Code Smell Register (with planned remedies)

• Suitability: 4
• Pros: Makes technical debt visible and actionable; supports refactoring prioritization.
• Cons: Can become a dumping ground; needs regular triage; subjective smell naming.

3. Design Invariants Catalog

• Suitability: 5
• Pros: Prevents accidental violations; drives property-based tests; improves reliability.
• Cons: Extracting invariants is hard; needs ongoing upkeep; can be too abstract if not linked to tests.

4. ADR Updates (Accepted/Deprecated)

• Suitability: 5
• Pros: Keeps decisions current; avoids fossilized docs; improves auditability.
• Cons: Overhead if frequent; needs concise writing; decisions can be politicized.

5. Observability Check (Logs/Metrics/Traces review)

• Suitability: 4
• Pros: Validates behavior under load; helps find refactoring candidates; aligns with SLOs.
• Cons: Requires tooling; non-trivial to attribute signals to design issues; can be noisy.

How to chain artifacts with human checkpoints

• Phase 1 → Phase 2: Human validates story value and testability; select 2–3 artifacts (User Story, Gherkin, Example Mapping).
• Phase 2 → Phase 3: Human approves minimal design and contracts; pick 2–3 (Sequence Sketch, API Contract, ADR).
• Phase 3 → Phase 4: Human ensures slices are small and tests failing initially; pick 2–3 (Test Skeletons, Feature Flag Plan, Vertical Slice Plan).
• Phase 4 → Next iteration: Human reviews Refactoring Log and ADR updates; confirms invariants; feeds back into new stories.

Minimal templates you can copy into prompts

User Story + Acceptance

• Story: As a [role], I want [capability], so that [benefit].
• Acceptance (Gherkin): Given [context] When [action] Then [outcome]
• Examples: [input] → [output]
• Constraints/Non-goals/Risks

Design Pack

• CRC: [Concept] Responsibilities: […] Collaborators: […]
• Sequence: [Actor] → [Component]: [Message]; include failure path
• API: Request/Response JSON examples; errors; invariants
• ADR: Context, Decision, Alternatives, Consequences

Implementation Pack

• Vertical Slice: [goal]; acceptance criteria covered; demo plan
• Tests: acceptance test name(s); unit test name(s)
• Ports & Stubs: [interface]; [adapter]; TODOs
• Flag Plan: flag name, default, rollout steps, metrics
• Task Board: tasks, DoD, risks

Improvement Pack

• Refactoring Log: Change, Motivation, Tests impacted, Rollback, Links
• Smell Register: Name, Location, Principle, Remedy
• Invariants: [rule] → tests [name]; monitoring signal [metric]
• ADR Update: Status change with reasoning
• Observability Check: Before/after metrics; trace notes

If you share a concrete feature, I can instantiate these artifacts and tailor the selection per phase to keep the process light while ensuring each transition is well-supported.