arreio 1.0.0-dev.1

package/skills/plan/references/task-slicing-rules.md

@@ -0,0 +1,220 @@
+---
+title: Task Slicing Rules
+description: Reference for the Tasks phase. Defines how to decompose a plan's implementation units into Acceptance-Criterion-sized task files — one task per AC, one test per task, TDD-ordered, dependency-ordered, and registered in the index.
+type: reference
+version: 2.0
+timestamp: "2026-08-07"
+---
+
+# Task Slicing Rules
+
+This file documents the rules for decomposing a finalized plan into individual task files during the **Tasks** phase (Phase 5). The model is **one task per Acceptance Criterion**, with **one test per task** (test written first, Red→Green→Refactor), ordered by dependency, saved to `docs/tasks/<plan-id>/`, and registered in `docs/tasks/<plan-id>/index.md`.
+
+## When to Apply
+
+Task slicing runs after the Generate phase has produced a validated Final Plan. The Tasks phase reads the plan's Implementation Units — each of which carries one or more **Acceptance Criteria** — and produces one task file per criterion.
+
+## Core Slicing Heuristics
+
+### Rule 1: One Task Per Acceptance Criterion (Default)
+
+Each **Acceptance Criterion** on an Implementation Unit becomes **exactly one task**. The task inherits the unit's goal, dependencies, and file paths, and gets its **own dedicated test file** in `files.test`. A task never spans more than one Acceptance Criterion.
+
+### Rule 2: Never Split Within an Acceptance Criterion
+
+If a single Acceptance Criterion would need > 5 files or > 1 day of effort, do **not** slice the task partway through the criterion. Instead, **split the criterion into two or more finer sub-criteria** in the originating unit, then create one task per sub-criterion. This keeps the one-task-one-test-one-AC invariant intact.
+
+Split criteria use sub-identifiers: `U2` → `U2a`, `U2b` (letters, not extra digits). Never renumber the original units or criteria.
+
+### Rule 3: No Merging Across Criteria
+
+Do not merge tasks. A task always carries exactly one Acceptance Criterion. (Adjacent trivial units that genuinely share a single criterion are, by definition, already one criterion — they yield one task.)
+
+### Rule 4: Preserve Dependency Order
+
+Tasks must be ordered so a task's dependencies are fully satisfied by earlier tasks. Never produce a task that depends on a later task.
+
+```
+valid ordering:
+  T1 (no deps) → T2 (deps: T1) → T3 (deps: T1, T2)
+
+invalid ordering:
+  T2 (deps: T3) → T1 (no deps) → T3 (deps: T1)
+```
+
+### Rule 5: Never Renumber Units or Criteria
+
+When slicing, preserve the original `U#` identifiers from the plan. If a unit's criteria are split (Rule 2), use sub-identifiers (e.g., `U2a`, `U2b`). Never renumber — units and criteria are referenced by the plan and downstream execution.
+
+## Sizing Guidance by Plan Tier
+
+| Tier     | Target Tasks | Max Files Per Task | Suggested Max Effort Per Task |
+| -------- | ------------ | ------------------ | ----------------------------- |
+| Fast     | 1–3          | 3                  | Half day                      |
+| Standard | 4–8          | 5                  | 1 day                        |
+| Deep     | 8–15         | 5                  | 1 day                        |
+
+These are **guidance**, not hard limits. If a tier's task count would exceed the target, split criteria finer (Rule 2). If it would fall short, that is acceptable — never manufacture criteria to hit a target, and never merge criteria to reduce the count.
+
+## Task File Schema
+
+Each task file is markdown with this schema (see [task.md template](templates/artifacts/task.md)):
+
+```yaml
+---
+id: <plan-id>-T<NN>
+title: "[Task title]"
+plan-id: <plan-id>
+unit: U<NN> | U<NN><letter>
+tier: fast | standard | deep
+status: not-started
+priority: P0 | P1 | P2
+dependencies: [<task-id>, ...]
+files:
+  create: [path/to/file, ...]
+  modify: [path/to/file, ...]
+  test: [path/to/test]          # exactly one — the test for this task's AC
+estimated-effort: "<hours or days>"
+timestamp: ISO-8601 timestamp
+---
+
+# [Task Title]
+
+## Goal
+[Inherited from the unit, scoped to this one criterion. 1-2 sentences.]
+
+## Acceptance Criterion
+[Exactly one, single, verifiable criterion this task delivers.]
+
+## Steps
+1. **Red — Write the failing test:** add the test at `files.test[0]` asserting this Acceptance Criterion. Run it and confirm it fails for the right reason.
+2. **Green — Implement:** add the minimum code in `files.create`/`files.modify` to make the test pass.
+3. **Refactor:** clean up naming, duplication, and structure while keeping the test green.
+
+## Test Scenarios
+- [Scenario]: [Input -> Expected Outcome]   # the assertion(s) for this criterion (may be one)
+
+## Acceptance Criteria
+- [ ] [This task's single Acceptance Criterion, restated as a checkable box]
+
+## Dependencies
+- [task-id]: [why this task must complete first, or "None"]
+
+## Notes
+[Any context, gotchas, references to learnings, or links to related tasks. Optional.]
+```
+
+## File-Naming Convention
+
+Task files are named:
+
+```
+docs/tasks/<plan-id>/T<NN>-<kebab-case-name>.md
+```
+
+Where:
+
+- `<plan-id>` — The plan's ID (e.g., `2026-07-03-001`)
+- `<NN>` — Zero-padded 2-digit task number, matching dependency order (01, 02, ..., 10)
+- `<kebab-case-name>` — Short descriptive name (e.g., `redis-client-setup`)
+
+**Example:**
+
+```
+docs/tasks/2026-07-03-001/
+  T01-redis-client-setup.md
+  T02-session-store-interface.md
+  T03-session-middleware-refactor.md
+```
+
+## Task ID Generation
+
+```
+1. Read the plan-id from the Final Plan artifact.
+2. Tasks are numbered NN in dependency order (01, 02, ...).
+3. If a criterion is split (Rule 2): use letters, not extra digits: U2a -> T02a, T02b.
+4. The `unit` field records the originating unit (or sub-ID).
+```
+
+## Dependency Ordering Algorithm
+
+```
+function order_tasks(tasks):
+  # tasks is a list of {id, unit, dependencies, ...}
+  ordered = []
+  remaining = copy(tasks)
+  while remaining:
+    ready = [t for t in remaining if all(d in ordered for d in t.dependencies)]
+    if not ready:
+      raise CycleError("Dependency cycle detected among: " + remaining)
+    # Sort ready tasks by original unit number for stable ordering
+    ready.sort(by: unit_number)
+    ordered.extend(ready)
+    remaining.remove(ready)
+  return ordered
+```
+
+**Cycle handling:** If no task is ready (all have unsatisfied dependencies), a cycle exists. Log the error, surface the involved tasks to the user, and ask whether to break the cycle manually (by removing a dependency) or abort.
+
+## Priority Assignment
+
+| Priority | Criteria                                           |
+| -------- | -------------------------------------------------- |
+| P0       | Blocks all other tasks (foundation, infra, schema) |
+| P1       | On the critical path but not blocking             |
+| P2       | Can be deferred or parallelized                    |
+
+Default: Phase 1 (Foundation) tasks → `P0`; Phase 2 (Integration) → `P1`; Phase 3 (Rollout)/optional → `P2`. Adjust based on risk analysis (a rollout task mitigating a HIGH risk may be `P1`).
+
+## Index Registration
+
+After saving all task files, update `docs/tasks/<plan-id>/index.md`:
+
+```markdown
+## <plan-id> — [Plan Title]
+
+- [ ] T01 — [Task title] (`U1`, AC: [criterion]) — `docs/tasks/<plan-id>/T01-<name>.md`
+- [ ] T02 — [Task title] (`U2a`, AC: [criterion]) — `docs/tasks/<plan-id>/T02-<name>.md`
+```
+
+Mark each task with `- [ ]` (unchecked). The Work skill will check them off as tasks complete.
+
+## Error Handling
+
+| Scenario                                | Recovery                                        |
+| --------------------------------------- | ----------------------------------------------- |
+| `docs/tasks/` directory missing         | Create it; create `<plan-id>/` subdirectory     |
+| `docs/tasks/<plan-id>/index.md` missing | Create empty index; append the plan's section   |
+| Dependency cycle detected among tasks   | Surface cycle to user; ask to break or abort    |
+| Criterion would need > 5 files / > 1 day | Split the criterion into finer sub-criteria (Rule 2) |
+| Plan has no Implementation Units        | Abort; ask user to re-run Generate phase        |
+| Task count exceeds tier target          | Log warning; split criteria finer, or proceed (targets are guidance) |
+
+## Interaction Mode Behavior
+
+Per [interaction-mode-propagation.md](interaction-mode-propagation.md), the Tasks phase **always asks the user**, even in Autopilot mode:
+
+| Mode      | Behavior                                         |
+| --------- | ------------------------------------------------ |
+| Detailed  | Show full task list + full file content; ask to save |
+| Smart     | Show task list summary; ask to save              |
+| Autopilot | Show task count; ask to save (always asks)       |
+
+The question asked:
+
+```
+The plan has been sliced into <N> tasks (T01–T<NN>); one per Acceptance Criterion,
+each with its own failing-first test.
+Would you like me to create the task files in docs/tasks/<plan-id>/?
+  - Yes: Create all task files and update the index
+  - Review: Show the task list first, then ask again
+  - No: Skip task creation (plan is still saved for manual slicing)
+```
+
+## Notes
+
+- Tasks are the handoff point to the Work skill (`work/SKILL.md`); each must be self-contained around a single Acceptance Criterion and its test — executable without re-reading the full plan.
+- Every task is Test-Driven: write the failing test first, confirm Red, implement to Green, refactor while green.
+- One test per task (one test per AC). Never one test asserting multiple criteria.
+- Preserve the plan's `Related Learnings` in task files touching the relevant domain, so the Work phase has context.
+- If the user declines task creation, the plan remains the unit of work — the user can slice manually later.

package/skills/plan/references/templates/artifacts/design.md

@@ -0,0 +1,134 @@
+---
+title: Design Artifact
+description: Template for the Design Artifact produced by the Design phase. Captures the chosen approach, implementation units, complexity assessment, and alternatives considered for downstream generation.
+type: template
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Design Artifact
+
+The product of the **Design** phase (Phase 3) is a structured design object that the **Generate** phase consumes to render the final plan. It captures the chosen approach, the implementation unit decomposition, the complexity assessment, and the alternatives considered (and why they were rejected).
+
+When the **Design** phase completes, it produces a design block (as markdown) with this schema:
+
+## Schema
+
+```yaml
+type: design
+design-id: YYYY-MM-DD-NNN-design
+scope-id: YYYY-MM-DD-NNN-scope        # Inherited from Scope phase; traceability link
+research-id: YYYY-MM-DD-NNN-research  # Inherited from Research phase
+status: complete
+interactionMode: detailed | smart | autopilot
+timestamp: ISO-8601 timestamp (e.g., 2026-07-04T14:30:00Z)
+complexity: TRIVIAL | LOW | MEDIUM | HIGH | VERY_HIGH
+tier_recommended: fast | standard | deep
+
+# Design
+
+## Approach
+[1-3 sentence summary of the chosen approach and why it fits the scoped context and research findings]
+
+## High-Level Technical Design
+[ONE of: Mermaid diagram, pseudo-code sketch, or data-flow map — directional guidance, not implementation specification]
+
+## Implementation Units (Phased)
+
+### Phase 1: Foundation
+- U1. **[Unit Name]**
+  - Goal: [What this unit accomplishes]
+  - Dependencies: None
+  - Files:
+    - Create: `path/to/file`
+    - Test: `path/to/test`
+  - Acceptance Criteria:
+    - [Single, verifiable criterion — each criterion later becomes exactly one task and one test]
+  - Test Scenarios:
+    - [Scenario]: [Input -> Expected Outcome]
+
+- U2. **[Unit Name]**
+  - Goal: [What this unit accomplishes]
+  - Dependencies: U1
+  - Files:
+    - Create: `path/to/file`
+  - Acceptance Criteria:
+    - [Single, verifiable criterion]
+  - Test Scenarios:
+    - [Scenario]: [Input -> Expected Outcome]
+
+### Phase 2: Integration
+- U3. **[Unit Name]**
+  - Goal: [What this unit accomplishes]
+  - Dependencies: U1, U2
+  - Files:
+    - Modify: `path/to/file`
+  - Acceptance Criteria:
+    - [Single, verifiable criterion]
+  - Test Scenarios:
+    - [Scenario]: [Input -> Expected Outcome]
+
+### Phase 3: Rollout (if applicable)
+- U4. **[Unit Name]**
+  - Goal: [What this unit accomplishes]
+  - Dependencies: U3
+  - Files:
+    - Modify: `path/to/file`
+  - Acceptance Criteria:
+    - [Single, verifiable criterion]
+
+## Complexity Assessment
+- scope_breadth: 0-3
+- integration_surface: 0-3
+- risk_level: LOW | MEDIUM | HIGH | CRITICAL   # Inherited from Research phase
+- novelty: 0-3
+- data_migration: 0-3
+- total: [sum]
+- complexity: TRIVIAL | LOW | MEDIUM | HIGH | VERY_HIGH
+
+## Alternative Approaches Considered
+- **[Approach Name]**: [Description] → **Rejected because:** [Rationale]
+- **[Approach Name]**: [Description] → **Rejected because:** [Rationale]
+
+## Related Learnings
+- docs/learn/XXX.md — [1-line applicability note]
+- (List from docs/learn/index.md; empty list if none)
+
+## Learning Gaps
+- [Gap name] — [Follow-up action via /learn]
+```
+
+Also save the design artifact to `docs/plans/.design/<design-id>.md` for future reference or reuse. The `interactionMode` and `complexity` values flow into the Generate artifact for tier selection.
+
+## Validation Rules
+
+- **Approach:** Required. Must reference the scoped context and research findings (not invented in isolation).
+- **High-Level Technical Design:** Required. Must be ONE of: Mermaid diagram, pseudo-code sketch, or data-flow map. Directional only — not an implementation specification.
+- **Implementation Units:** Required. At least one unit (U1). Each unit must have a Goal, Dependencies, Files, and **Acceptance Criteria** (at least one; each criterion becomes exactly one task and one test in the Tasks phase). Test Scenarios required for units in phases 1–2; optional for rollout-only units.
+- **Complexity Assessment:** Required. All five dimensions scored 0–3; `total` must equal the sum; `complexity` must match the threshold mapping.
+- **Alternative Approaches:** Required for MEDIUM+ complexity; at least 1 alternative. For HIGH/VERY_HIGH, at least 2 alternatives. For TRIVIAL/LOW, may be empty.
+- **Related Learnings:** Required (may be empty list). Must reference `docs/learn/index.md`.
+- **Learning Gaps:** Required (may be empty list). Inherited from Scope phase; updated if design reveals new gaps.
+- **scope-id / research-id:** Required. Must match the upstream artifacts for cross-phase consistency (see [error-handling.md](../../error-handling.md)).
+
+## Usage in Workflow
+
+1. **Design Phase** produces this artifact from the Scoped Context and Research Findings
+2. **Design Phase Step 0** validates the incoming Scoped Context and Research Findings (see [error-handling.md](../../error-handling.md))
+3. **Generate Phase** reads the `complexity` and `tier_recommended` fields to select the plan tier (see [plan-tier-selection.md](../../plan-tier-selection.md))
+4. **Generate Phase** renders the final plan from the units and alternatives captured here
+
+## Missing Field Recovery
+
+If the Design Artifact is incomplete at validation, use this recovery workflow:
+
+| Field                       | Validation                       | Recovery                                                                                           |
+| --------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Approach                    | Non-empty, references context    | Re-run Design phase; ask user to clarify approach                                                  |
+| High-Level Technical Design | One of three formats present     | Ask user to choose diagram, pseudo-code, or data-flow map                                          |
+| Implementation Units        | At least U1 with Goal/Files      | Re-run Design decomposition step                                                                   |
+| Complexity Assessment       | All 5 dimensions + total + level | Recompute from units; see [design-complexity-assessment.md](../../design-complexity-assessment.md) |
+| Alternative Approaches      | Count matches complexity tier    | Ask user for additional alternatives if below threshold                                            |
+| scope-id / research-id      | Matches upstream artifacts       | Reject; ask Orchestrator to re-run from the mismatched phase                                       |
+
+**Note:** If the Approach or Implementation Units cannot be produced, abort planning and ask the user to revisit the research phase — the scoped context may be insufficient for design.

package/skills/plan/references/templates/artifacts/final-plan.md

@@ -0,0 +1,265 @@
+---
+title: Final Plan Artifact
+type: template
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Plan Templates
+
+This document contains the planning template supported by the Plan skill.
+
+### Template
+
+````markdown
+---
+plan-id: YYYY-MM-DD-NNN
+type: plan
+title: "[Plan title]"
+status: complete
+tier: fast | standard | deep
+tier_recommended: fast | standard | deep
+complexity: TRIVIAL | LOW | MEDIUM | HIGH | VERY_HIGH
+risk: Low | Medium | High | Critical
+scope-id: YYYY-MM-DD-NNN-scope
+research-id: YYYY-MM-DD-NNN-research
+design-id: YYYY-MM-DD-NNN-design
+interactionMode: detailed | smart | autopilot
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+version: 1.0
+---
+
+## Overview
+
+[1-2 sentence summary: what the plan delivers and why it matters]
+
+# [Title]
+
+## High-Level Technical Design
+
+> **Note:** This is directional guidance for review, not an implementation specification to copy. The implementation phase will determine specific naming, abstractions, and code structure.
+
+[Provide ONE of these:]
+
+**Mermaid Diagram:**
+
+```mermaid
+sequenceDiagram
+    participant A as Component A
+    participant B as Service B
+    A->>B: request
+    B-->>A: response
+```
+
+**OR Pseudo-Code Sketch:**
+
+```
+on user_action:
+  validate input
+  if valid:
+    process and store
+    trigger event
+  else:
+    return error
+```
+
+**OR Data-Flow Map:**
+
+```
+User Input → Validation → Processing → Storage → Event Bus → Notification
+```
+
+## Implementation Units (Phased)
+
+### Phase 1: Foundation
+
+- U1. **[Unit Name]**
+  - **Goal:** [What this unit accomplishes]
+  - **Dependencies:** None
+  - **Files:**
+    - Create: `path/to/file`
+    - Test: `path/to/test`
+  - **Acceptance Criteria:**
+    - [Single, verifiable criterion — each criterion later becomes exactly one task and one test]
+  - **Test Scenarios:**
+    - [Scenario]: [Input -> Expected Outcome]
+
+- U2. **[Unit Name]**
+  - **Goal:** [What this unit accomplishes]
+  - **Dependencies:** U1
+  - **Files:**
+    - Create: `path/to/file`
+  - **Acceptance Criteria:**
+    - [Single, verifiable criterion]
+  - **Test Scenarios:**
+    - [Scenario]: [Input -> Expected Outcome]
+
+### Phase 2: Integration
+
+- U3. **[Unit Name]**
+  - **Goal:** [What this unit accomplishes]
+  - **Dependencies:** U1, U2
+  - **Files:**
+    - Modify: `path/to/file`
+  - **Acceptance Criteria:**
+    - [Single, verifiable criterion]
+  - **Test Scenarios:**
+    - [Scenario]: [Input -> Expected Outcome]
+
+### Phase 3: Rollout (if applicable)
+
+- U4. **[Unit Name]**
+  - **Goal:** [What this unit accomplishes]
+  - **Dependencies:** U3
+  - **Files:**
+    - Modify: `path/to/file`
+  - **Acceptance Criteria:**
+    - [Single, verifiable criterion]
+
+## Alternative Approaches Considered
+
+- **[Approach Name]**: [Description] → **Rejected because:** [Rationale for not choosing this approach]
+- **[Approach Name]**: [Description] → **Rejected because:** [Rationale]
+
+## Risk Analysis & Mitigation
+
+| Risk                        | Impact | Mitigation                                    |
+| --------------------------- | ------ | --------------------------------------------- |
+| [Specific risk description] | High   | [Concrete step to prevent or recover from it] |
+| [Another risk]              | Medium | [Mitigation strategy]                         |
+
+## Operational / Rollout Notes
+
+[Include if applicable:]
+
+- Feature flags: `feature.new_system` controls activation
+- Monitoring: Add metrics for [key operations]
+- Data migration: [Steps to migrate existing data]
+- Rollback plan: [How to safely revert if issues arise]
+- Performance baseline: [Expected throughput, latency targets]
+
+## Related Learnings
+
+- **[Learning Title]** — `docs/learn/XXX.md` — [1-line applicability note]
+- (List relevant entries from `docs/learn/index.md`; if none apply, state "No relevant learnings found")
+
+## Learning Gaps
+
+- [Any gap identified during planning that should be documented after implementation via `/learn`]
+````
+
+### Example
+
+```markdown
+---
+plan-id: 2026-05-01-001
+type: plan
+title: "Migrate Session Storage from In-Memory to Redis"
+status: complete
+tier: standard
+tier_recommended: standard
+complexity: HIGH
+risk: High
+scope-id: 2026-05-01-001-scope
+research-id: 2026-05-01-001-research
+design-id: 2026-05-01-001-design
+interactionMode: smart
+created: 2026-05-01
+updated: 2026-05-01
+version: 1.0
+---
+
+# Migrate Session Storage from In-Memory to Redis
+
+## High-Level Technical Design
+
+**Session Lifecycle:**
+
+1. Request arrives with session cookie (JWT)
+2. Middleware validates JWT signature and expiration
+3. Extract session ID, fetch from Redis
+4. Attach session object to request context
+
+## Implementation Units (Phased)
+
+### Phase 1: Foundation
+
+- U1. **Redis Client and Session Store Interface**
+  - **Goal:** Create Redis client wrapper and session storage interface
+  - **Files:** `src/lib/redis-client.ts` · test: `src/lib/redis-client.test.ts`
+  - **Acceptance Criteria:**
+    - `SessionStore` interface with `get`/`save`/`delete` backs a Redis client that connects from `REDIS_URL` and retries on failure
+  - **Test Scenarios:** Store/retrieve session, TTL expiration, connection errors
+
+### Phase 2: Integration
+
+- U2. **Session Middleware Refactor**
+  - **Goal:** Integrate Redis session store into middleware
+  - **Files:** `src/middleware/session.ts` · test: `src/middleware/session.test.ts`
+  - **Acceptance Criteria:**
+    - Middleware loads a valid JWT-backed session from Redis and rejects invalid/expired sessions
+  - **Test Scenarios:** Valid JWT loading, invalid JWT rejection, store errors
+
+## Alternative Approaches Considered
+
+- **PostgreSQL**: Rejected — slower latency for session reads on critical path
+- **Stateless JWT-Only**: Rejected — cannot revoke sessions, increases cookie size
+- **Sticky Sessions**: Rejected — limits horizontal scaling, poor failover
+
+## Risk Analysis & Mitigation
+
+| Risk                    | Mitigation                                     |
+| ----------------------- | ---------------------------------------------- |
+| Redis outage            | HA mode (sentinel/cluster), monitoring, alerts |
+| Performance degradation | Benchmark latency <2ms p99, connection pooling |
+
+## Operational / Rollout Notes
+
+- Feature flags: `feature.redis_sessions_dual_write`, `feature.redis_sessions_only`
+- Gradual cutover with dual-write phase for validation
+- Sessions expire naturally; no explicit data migration needed
+
+## Related Learnings
+
+(List relevant entries from `docs/learn/index.md`)
+
+## Learning Gaps
+
+- Document session architecture decisions and Redis failover patterns
+```
+
+---
+
+## Overview
+
+Plans guide complex projects through structured phases. Include technical design, phased units, alternatives analysis, risk mitigation, and operational notes.
+
+---
+
+## Template Usage Rules
+
+### Required Sections
+
+Which sections a plan includes is **tier-driven**, not fixed. See [plan-tier-selection.md](../../plan-tier-selection.md) and the Generate phase ([generate.md](../../../modules/generate.md)) for the Fast/Standard/Deep section matrix (Fast omits Alternative Approaches, Operational Notes, and Learning Gaps; Standard and Deep add them). Do not render a section the tier marks optional and empty.
+
+### File Path Requirements
+
+- All file paths in plans must be **repository-relative** (e.g., `src/main.js`, `docs/plans/YYYY-MM-DD-NNN-name.md`)
+- Never use absolute paths (e.g., `/home/user/project/src/main.js`)
+- Use backtick inline code formatting for file paths: `` `path/to/file` ``
+
+### Learnings Embedding Rules
+
+- Every plan **must** include a `## Related Learnings` section
+- Scan `docs/learn/index.md` for relevant entries
+- Include file path and a 1-line applicability rationale per learning
+- If no relevant learnings exist, state: "No relevant learnings found"
+- Add a `## Learning Gaps` section for areas where knowledge is missing but needed
+- Learning gaps should include a follow-up action to document via `/learn`
+
+### Naming Convention
+
+- Plan files: `docs/plans/YYYY-MM-DD-NNN-<kebab-case-name>.md`
+- U-ID format: `U1`, `U2`, ... `UX` (never renumber)
+- Frontmatter required fields: see the Final Plan frontmatter in the template above and [error-handling.md](../../error-handling.md) — `plan-id`, `type`, `title`, `status`, `tier`, `tier_recommended`, `complexity`, `risk`, `scope-id`, `research-id`, `design-id`, `interactionMode`, `created`, `updated`, `version`

package/skills/plan/references/templates/artifacts/research-findings.md

@@ -0,0 +1,50 @@
+---
+title: Research Findings Artifact
+description: Template for the Research Findings Artifact produced by the Research phase. Captures research findings, insights, and relevant information for downstream phases.
+type: template
+version: 1.1
+timestamp: "2026-08-07"
+---
+
+# Output: Research Findings
+
+After completing the workflow, produce a research findings block (in memory or as markdown):
+
+```yaml
+type: research
+research-id: YYYY-MM-DD-NNN-research
+scope-id: YYYY-MM-DD-NNN-scope        # Inherited from Scope phase; traceability link
+status: complete
+interactionMode: detailed | smart | autopilot
+timestamp: ISO-8601 timestamp (e.g., 2026-07-04T14:30:00Z)
+
+# Research Findings
+
+## Patterns Found
+- `path/to/pattern/file` — [pattern description]
+
+## High-Risk Detection
+- Detected areas: [list]
+- Risk Level: CRITICAL | HIGH | MEDIUM | LOW
+- External Research Recommended: YES | NO
+
+## Tech Stack
+- [Framework]: [version]
+- [Language]: [version]
+- [Database]: [version]
+- [Key libraries]: [versions]
+
+## External Research
+- Needed: YES | NO
+- Guidance: [librarian query or web search suggestion]
+- Status: completed | skipped | declined
+
+## Technical Constraints
+- [Constraint 1]
+- [Constraint 2]
+
+## Findings Summary
+[2-3 sentence overview of all findings]
+```
+
+This findings object is passed to `design` (Phase 3) for the design phase.