fix: improve experience document types and templates

Author: ivklgn

.archcore/.sync-state.json

@@ -159,6 +159,21 @@
       "source": "telemetry/telemetry-provider-selection.rfc.md",
       "target": "telemetry/posthog-telemetry-implementation.plan.md",
       "type": "related"
+    },
+    {
+      "source": "dir/categories-and-document-types.doc.md",
+      "target": "dir/archcore-directory-structure.guide.md",
+      "type": "related"
+    },
+    {
+      "source": "dir/categories-and-document-types.doc.md",
+      "target": "dir/free-form-directory-rules.rule.md",
+      "type": "related"
+    },
+    {
+      "source": "dir/categories-and-document-types.doc.md",
+      "target": "dir/free-form-directory-structure.adr.md",
+      "type": "related"
     }
   ]
 }

.archcore/dir/categories-and-document-types.doc.md

@@ -0,0 +1,48 @@
+---
+title: "Categories and Document Types"
+status: accepted
+---
+
+## Overview
+
+Archcore organizes documents into three virtual categories — **vision**, **knowledge**, and **experience**. The category is derived from the document type in the filename (`slug.type.md`), not from the directory path.
+
+## Vision
+
+Documents that describe the future: what we want to build and why.
+
+| Type   | Purpose                                                    |
+| ------ | ---------------------------------------------------------- |
+| `prd`  | Product requirements — goals, scope, acceptance criteria   |
+| `idea` | A concept worth exploring — problem, value, rough approach |
+| `plan` | A concrete implementation plan with phased tasks           |
+
+## Knowledge
+
+Documents that capture what we know: decisions, standards, and reference material.
+
+| Type      | Purpose                                                                  |
+| --------- | ------------------------------------------------------------------------ |
+| `adr`     | A technical decision that has been made, with context and alternatives   |
+| `rfc`     | A proposal open for review before a decision is made                     |
+| `rule`    | A mandatory standard — imperative statements with good/bad examples      |
+| `guide`   | Step-by-step instructions for completing a task                          |
+| `doc`     | General reference — tables, registries, explanations                     |
+| `project` | Project overview with architecture, components, and getting-started info |
+
+## Experience
+
+Documents that encode proven patterns and lessons from practice.
+
+| Type        | Purpose                                                                             |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `task-type` | A proven workflow for a recurring implementation task — steps, examples, pitfalls   |
+| `cpat`      | A code pattern change — how and why a convention or approach changed (was → became) |
+
+## Choosing the Right Type
+
+- **rule vs doc** — rule prescribes behavior ("Always do X") with enforcement. doc describes what exists. Descriptive content → doc.
+- **adr vs rfc** — adr = decision already final. rfc = proposal open for feedback.
+- **guide vs doc** — guide has sequential steps to follow. doc is non-sequential reference to look up.
+- **task-type vs guide** — task-type is a reusable pattern for a class of tasks (e.g., "how to create a UI-kit component"). guide is instructions for a specific one-time procedure.
+- **cpat vs adr** — cpat focuses on a code pattern change with before/after examples. adr records a broader architectural decision with alternatives and consequences.

internal/mcp/server.go

@@ -22,7 +22,7 @@ Example structures:
 Document types and their virtual categories:
   knowledge: adr (decisions), rfc (proposals), rule (standards), guide (how-tos), doc (reference), project (project overview)
   vision:    prd (requirements), idea (concepts), plan (action plans)
-  experience: task-type (recurring workflows), cpat (corrective/preventive actions)
+  experience: task-type (typical task patterns), cpat (code pattern changes)
 
 DOCUMENT RELATIONS:
 Documents can be linked with directed relations stored in the sync manifest.
@@ -53,8 +53,8 @@ WHEN TO CREATE:
 - Step-by-step instructions for completing a task → guide
 - Reference information, registries, lookup tables, or general documentation → doc
 - A project overview with architecture, components, and getting-started info → project
-- A recurring task pattern or checklist is identified → task-type
-- A bug or incident is root-caused and needs prevention tracking → cpat
+- A proven workflow for a recurring implementation task is documented → task-type
+- A coding pattern, convention, or approach has deliberately changed → cpat
 - A product concept or technical idea needs capturing → idea
 - An implementation plan with tasks is formed → plan
 - Product requirements with goals, scope, and acceptance criteria → prd

internal/mcp/tools/create_document.go

@@ -43,10 +43,10 @@ Document types and when to use each:
                 § required sections: Idea, Value, Possible Implementation, Risks and Constraints
   plan      — A concrete implementation plan with defined tasks
                 § required sections: Goal, Tasks (phased), Acceptance Criteria, Dependencies
-  task-type — A recurring workflow pattern or task checklist
-                § required sections: When to Use, Fields, Workflow, Examples
-  cpat      — A corrective/preventive action record tied to a bug or incident
-                § required sections: Classification, Problem, Root Cause, Action (Corrective/Preventive)
+  task-type — A proven pattern for a typical recurring implementation task
+                § required sections: What, When to Use, Steps, Example, Things to Watch Out For
+  cpat      — A code pattern change: documents how and why a convention or approach changed
+                § required sections: What Changed, Why, Before, After, Scope
 
 TYPE DISAMBIGUATION:
 - rule vs doc: rule prescribes behavior ("Always do X") with good/bad examples and enforcement. doc describes what exists (tables, registries, explanations). Descriptive content → doc.

internal/mcp/tools/create_document_test.go

@@ -262,7 +262,7 @@ func TestHandleCreateDocument_AllTypes(t *testing.T) {
 		{"guide", "knowledge", "## Steps"},
 		{"doc", "knowledge", "## Content"},
 		{"task-type", "experience", "## When to Use"},
-		{"cpat", "experience", "### Classification"},
+		{"cpat", "experience", "## What Changed"},
 		{"prd", "vision", "### Product Vision Statement"},
 		{"idea", "vision", "### Problem / Opportunity"},
 		{"plan", "vision", "## Tasks"},

internal/mcp/tools/list_documents.go

@@ -26,7 +26,7 @@ Use the returned paths directly as input to get_document. Do not construct paths
 			mcp.WithStringItems(),
 		),
 		mcp.WithString("category",
-			mcp.Description(`Filter by virtual category (derived from document type, not directory). Use "knowledge" for decisions/standards/guides/docs/proposals, "vision" for requirements/ideas/plans, "experience" for workflows and corrective actions.`),
+			mcp.Description(`Filter by virtual category (derived from document type, not directory). Use "knowledge" for decisions/standards/guides/docs/proposals, "vision" for requirements/ideas/plans, "experience" for task patterns and code pattern changes.`),
 			mcp.Enum("vision", "knowledge", "experience"),
 		),
 		mcp.WithString("status",

templates/templates.go

@@ -692,211 +692,73 @@ Answer to the question.
 }
 
 func generateTaskTypeTemplate() string {
-	return `## Description
-
-Brief description of this task type and when it should be used.
-
-### Purpose
+	return `## What
 
-Why this task type exists and what problems it solves.
+What this typical task covers and what the end result looks like.
 
 ## When to Use
 
-Use this task type when:
-
-- Condition 1: Description
-- Condition 2: Description
-- Condition 3: Description
-
-Do NOT use this task type when:
-
-- Condition 1: Use [alternative] instead
-- Condition 2: Use [alternative] instead
-
-## Fields
-
-### Required Fields
-
-| Field | Type | Description | Validation |
-|-------|------|-------------|------------|
-| Field 1 | Type | Description | Rules |
-| Field 2 | Type | Description | Rules |
-| Field 3 | Type | Description | Rules |
+Use when:
 
-### Optional Fields
+- Condition 1
+- Condition 2
 
-| Field | Type | Description | Default |
-|-------|------|-------------|---------|
-| Field 1 | Type | Description | Value |
-| Field 2 | Type | Description | Value |
+Do NOT use when:
 
-## Workflow
-
-### States
-
-| State | Description | Transitions |
-|-------|-------------|-------------|
-| Open | Initial state | In Progress |
-| In Progress | Being worked on | Review, Blocked |
-| Review | Awaiting review | Done, In Progress |
-| Blocked | Cannot proceed | In Progress |
-| Done | Completed | - |
-
-### State Diagram
-
-1. Open → In Progress
-2. In Progress → Review
-3. Review → Done (or back to In Progress)
-
-### Automation
-
-- Trigger 1: Action
-- Trigger 2: Action
-
-## Examples
+- Condition: use [alternative] instead
 
-### Example 1: [Scenario]
-
-**Title:** Example task title
-
-**Description:** Example description
-
-**Fields:**
-- Field 1: Value
-- Field 2: Value
-
-### Example 2: [Scenario]
-
-**Title:** Example task title
-
-**Description:** Example description
+## Steps
 
-## Acceptance Criteria Template
+1. Step one — what to do and where (@path/to/file)
+2. Step two — what to do next
+3. Step three — final checks
 
-For tasks of this type, acceptance criteria should include:
+## Example
 
-- [ ] Criterion 1
-- [ ] Criterion 2
-- [ ] Criterion 3
+` + "```" + `
+// Small code snippet or @-reference to a real implementation
+` + "```" + `
 
-## Related Task Types
+## Things to Watch Out For
 
-- Task Type 1: When to use instead
-- Task Type 2: When to use in combination
+- Pitfall or gotcha 1
+- Edge case to keep in mind
+- Common mistake to avoid
 `
 }
 
 func generateCPATTemplate() string {
-	return `## Overview
-
-Brief description of this corrective/preventive action.
-
-### Classification
-
-- Type: [Corrective/Preventive/Both]
-- Severity: [Critical/High/Medium/Low]
-- Status: [Open/In Progress/Resolved/Verified]
-
-## Context
+	return `## What Changed
 
-### Background
+The pattern, convention, or approach that changed.
 
-Describe the background and context that led to this CPAT.
+## Why
 
-### Discovery
+What problem the old way caused and why the change was needed.
 
-How was this issue discovered?
+## Before
 
-- Discovery method: [Audit/Incident/Review/Other]
-- Discovery date: YYYY-MM-DD
-- Discovered by: [Team/Role]
-
-## Problem
-
-### Problem Statement
-
-Clear description of the problem or potential problem.
-
-### Impact
-
-What is the impact if not addressed?
-
-- Impact area 1: Description
-- Impact area 2: Description
-
-### Root Cause
-
-Root cause analysis:
-
-1. Primary cause: Description
-2. Contributing factor 1: Description
-3. Contributing factor 2: Description
-
-### Evidence
-
-Supporting evidence:
-
-- Evidence 1: Description or link
-- Evidence 2: Description or link
-
-## Action
-
-### Corrective Actions
-
-Immediate actions to address the problem:
-
-| Action | Owner | Due Date | Status |
-|--------|-------|----------|--------|
-| Action 1 | Name | Date | Status |
-| Action 2 | Name | Date | Status |
-| Action 3 | Name | Date | Status |
-
-### Preventive Actions
-
-Actions to prevent recurrence:
-
-| Action | Owner | Due Date | Status |
-|--------|-------|----------|--------|
-| Action 1 | Name | Date | Status |
-| Action 2 | Name | Date | Status |
-
-### Verification
-
-How will we verify the actions were effective?
-
-- Verification method 1: Description
-- Verification method 2: Description
-
-## Timeline
-
-| Milestone | Target Date | Actual Date | Notes |
-|-----------|-------------|-------------|-------|
-| Identified | Date | Date | |
-| Analysis Complete | Date | Date | |
-| Actions Started | Date | Date | |
-| Actions Complete | Date | Date | |
-| Verified | Date | Date | |
+` + "```" + `
+// Old pattern
+` + "```" + `
 
-## Stakeholders
+## After
 
-| Role | Name | Responsibility |
-|------|------|----------------|
-| Owner | Name | Overall accountability |
-| Assignee | Name | Implementation |
-| Reviewer | Name | Verification |
+` + "```" + `
+// New pattern
+` + "```" + `
 
-## Lessons Learned
+## Scope
 
-Key takeaways:
+Affected files and modules:
 
-- Lesson 1: Description
-- Lesson 2: Description
+- @path/to/affected/module
+- @path/to/another/file
 
-## References
+## Notes
 
-- Related incident: Link
-- Related documentation: Link
-- Similar CPATs: Link
+- Exceptions where the old pattern is still acceptable
+- Migration notes or timeline
 `
 }