aw-ecc 1.4.32 → 1.4.48

package/skills/tdd/interface-design.md

@@ -0,0 +1,31 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup

package/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/skills/tdd/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic

package/skills/tdd/tests.md

@@ -0,0 +1,61 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/skills/to-issues/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: to-issues
+description: Break a PRD, spec, or plan into local vertical slices that can feed `tasks.md` or optional tracker issues. Use when AW planning needs tracer-bullet work breakdown before implementation tasks.
+---
+
+# To Issues
+
+Break a plan into independently reviewable vertical slices.
+
+In AW, "issues" means implementation-ready work items by default, not necessarily remote GitHub/Linear/Jira issues. The normal output feeds `.aw_docs/features/<feature_slug>/tasks.md` and `state.json`. Publish remote issues only when the user explicitly asks and the target tracker is configured.
+
+## When To Use
+
+- `/aw:plan` is about to write `tasks.md` and the work needs a vertical breakdown.
+- A PRD or spec is too broad to hand directly to `/aw:build`.
+- The user asks to convert a plan into tickets, issues, slices, or implementation chunks.
+
+## Process
+
+### 1. Gather Context
+
+Read the source plan, PRD, spec, or conversation context. If an external issue URL is supplied, fetch only the referenced issue and relevant comments.
+
+### 2. Draft Vertical Slices
+
+Each slice should deliver a narrow but complete path through the system. Avoid horizontal slices like "build all backend first" or "write all tests first".
+
+For each slice, capture:
+
+- **Title**: short behavior-oriented name
+- **Type**: `AFK` when an agent can execute from artifacts; `HITL` when a human decision/design review is required
+- **Goal**: the end-to-end behavior or proof this slice delivers
+- **Blocked by**: prior slices or decisions
+- **Acceptance criteria**: observable pass conditions
+- **Suggested validation**: command, test, review, or runtime proof
+- **Write scope**: exact or likely files/modules when known safely
+
+### 3. Check Granularity
+
+Prefer many thin slices over a few bulky phases. A good slice is independently demoable or verifiable, but still small enough to review and roll back.
+
+### 4. Hand Off To AW Tasks
+
+Return the approved or best-effort slice list to `aw-tasks` so it can create `tasks.md` with phases, file maps, validation commands, and dependency order.
+
+### 5. Optional Remote Publishing
+
+Only publish tracker issues when all of these are true:
+
+- the user explicitly asks for remote issue creation
+- the target tracker and project are known
+- labels/assignees/status conventions are known
+- parent issue handling is clear
+
+Never close or modify a parent issue as part of slice generation unless the user explicitly asks.
+
+## Guardrails
+
+- Do not require an issue tracker for AW planning.
+- Do not rely on external setup commands.
+- Do not write `tasks.md` directly unless the caller asks; return the slice model to `aw-tasks`.
+- Do not invent file paths when the codebase has not been inspected enough to infer them safely.

package/skills/to-prd/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: to-prd
+description: Synthesize existing conversation, repo context, and decisions into a local AW `prd.md`. Use when `/aw:plan` is in product/full mode, when product assumptions need to be frozen before spec/tasks, or when the user asks to turn discovery into a PRD.
+---
+
+# To PRD
+
+Turn already-gathered context into a local AW PRD.
+
+This skill does not require a project issue tracker and does not publish anything remotely unless the user explicitly asks for that as a separate action. Its default output is the canonical `.aw_docs/features/<feature_slug>/prd.md` content used by AW planning.
+
+## When To Use
+
+- `/aw:plan` is in `product` or `full` mode.
+- A fuzzy request needs product scope, success criteria, actors, or non-goals frozen before technical planning.
+- Existing discovery, tickets, conversation, screenshots, or notes are enough to synthesize a PRD.
+
+## When Not To Use
+
+- The request is already a well-defined technical change and `spec.md` can be written without product discovery.
+- The user explicitly asks for Markdown-only technical planning.
+- The needed product facts are missing. In that case, ask the smallest useful question or route through `grill-with-docs` first.
+
+## Process
+
+1. Gather only the context needed for the PRD:
+   - user request and conversation decisions
+   - relevant existing planning artifacts
+   - repo context only when it clarifies current behavior or constraints
+   - domain glossary and ADRs when they exist
+2. Identify the product shape:
+   - problem
+   - target users or actors
+   - desired outcome
+   - in-scope and out-of-scope behavior
+   - acceptance criteria
+   - risks, assumptions, dependencies, and open questions
+3. Write PRD-ready content for `.aw_docs/features/<feature_slug>/prd.md`.
+4. Preserve unresolved questions instead of inventing product facts.
+5. Hand the PRD back to `aw-plan` so the stage can decide whether `spec.md`, `design.md`, or `tasks.md` are still needed.
+
+## PRD Shape
+
+Use this structure unless the existing repo has a stricter local template:
+
+```md
+# <Feature Name> PRD
+
+## Goal
+
+## Problem
+
+## Users / Actors
+
+## Scope
+
+## Non-Goals
+
+## User Stories
+
+## Acceptance Criteria
+
+## Assumptions and Constraints
+
+## Risks and Mitigations
+
+## Open Questions
+```
+
+## Guardrails
+
+- Do not require a PRD for every technical plan.
+- Do not publish to GitHub, Linear, Jira, or any other tracker unless explicitly requested.
+- Do not create implementation tasks here; use `to-issues` or `aw-tasks` for vertical slice breakdown.
+- Do not turn a PRD into a contract for code files; keep file paths in `spec.md` or `tasks.md`.