@meyverick/agentic 5.0.2

package/skills/openspec-harden/evals/evals.json

@@ -0,0 +1,38 @@
+{
+  "skill_name": "openspec-harden",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Harden the proposal, specs, and tasks for the auth change with concrete file paths and test commands.",
+      "expected_output": "Agent loads openspec-harden skill and inspects proposal.md, design.md, specs/, and tasks.md to enrich them with grounded codebase context and exact paths.",
+      "files": [],
+      "assertions": [
+        "Skill activates on hardening request",
+        "Artifacts enriched with concrete paths",
+        "Source code is not edited"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Implement the tasks in tasks.md for the auth change and modify the codebase.",
+      "expected_output": "Agent does NOT activate openspec-harden. Implementation and code-writing are handled by openspec-apply-change; openspec-harden only enriches planning artifacts before apply.",
+      "files": [],
+      "assertions": [
+        "Anti-trigger fires: request routes to openspec-apply-change, not openspec-harden",
+        "No proposal hardening workflow executed",
+        "No planning artifacts modified"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Improve change for fresh agent by resolving either/or file paths into single targets.",
+      "expected_output": "Agent enriches tasks with single concrete paths and verify steps without implementing features.",
+      "files": [],
+      "assertions": [
+        "Single concrete paths assigned",
+        "Zero code mutations made to project files",
+        "Verify steps populated"
+      ]
+    }
+  ]
+}

package/skills/openspec-learn/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: openspec-learn
+description: >
+  Analyze reports from `openspec-report` to generate OpenSpec proposals for
+  skill improvements. Use when analyzing reports to plan skill creation,
+  improvements, or lifecycle actions. Do NOT use when proposing a new change
+  from scratch (use openspec-propose), generating reports from archived changes,
+  or implementing proposals.
+allowed-tools: Bash(openspec:*), Bash(node:*), Bash(mkdir:*), Bash(ls:*)
+license: MIT
+compatibility: Requires openspec CLI and bun.
+metadata:
+  author: agentic
+  version: "1.3.1"
+positive_triggers:
+  - "analyze reports and improve skills"
+  - "generate proposals from report insights"
+  - "process reports and create improvement plans"
+anti_triggers:
+  - "propose a new change from scratch"
+  - "generate a report from an archived change"
+  - "implement a proposal or apply changes"
+---
+
+# Openspec Learn
+
+Analyze reports and generate OpenSpec proposals for improvements.
+
+## Quick Start
+
+- **With argument**: Process single report: `./openspec/reports/<name>/`
+- **Without argument**: Process ALL reports: `./openspec/reports/*/` (excluding `archives/`)
+- **With store**: Forward selected `--store <id>` on applicable commands (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`); sticky for workflow; nearest-root if unselected
+
+## Workflow
+
+### Phase 1: Report Scanning
+
+```bash
+ls ./openspec/reports/ | grep -v archives
+```
+
+### Phase 2: Report Analysis
+
+**From report.md:** OKF frontmatter, problem statement, approach, specs, implementation, validation, trade-offs, follow-ups.
+
+**From assessment.md:** knowledge gaps, difficulty ratings, tool improvements, what could have helped.
+
+### Phase 2a: Semantic Collision Detection
+
+Scan existing skills for description overlap with proposed tool:
+
+```bash
+grep -r "description:" .agents/skills/*/SKILL.md ./project/skills/*/SKILL.md 2>/dev/null
+```
+
+Compare proposed tool's domain keywords against existing descriptions. If overlap detected → flag collision in proposal, suggest updating existing skill instead of creating new one.
+
+### Phase 2b: Trigger Metadata Extraction
+
+Extract trigger candidates from report assessment:
+- What queries/situations led to this change? → candidate positive_triggers
+- What was confusing or out-of-scope? → candidate anti_triggers
+
+Include as "Suggested Triggers" section in proposal.
+
+### Phase 2c: Ownership Pre-Check + Single-Responsibility Pre-Check
+
+**Ownership pre-check (MANDATORY, runs first).** Classify every candidate target skill by ownership using this precedence chain — recorded facts before conventions, conventions before residual judgment:
+
+1. Inside the agentic repo itself → `project/skills/*` is owned (editable only by the project owner and the owner's trusted assistant session)
+2. Listed in `.agents/skills/.agentic-manifest.json` → agentic-distributed → **external** (read-only for consumers)
+3. Located in `~/.pi/agent/skills/` (not created by this project) → **external**
+4. Explicit verdict in `.agents/skills/.ownership.json` (`{"owned": [...], "external": [...]}`) → as declared
+5. Named `openspec-*` and authored by OpenSpec (upstream path `.agents/skills/openspec-*`, frontmatter `author: openspec`) → **external** (public namespace claim; does NOT apply to agentic-authored `project/skills/openspec-{learn,report,harden}`, which remain owned at source per item 1 and read-only once installed elsewhere)
+6. Any other skill in the project's `.agents/skills/` → project-created → editable
+7. Unresolved after all checks → unknown = **external**, ask the user
+
+Rules:
+- Proposals MUST NOT target external skills. Never edit installed/upstream files under `.agents/skills/*` in place — consumer agents treat installed skills as read-only; the next atomic-replace install silently wipes in-place edits. Reroute improvements upstream or to project-local placements.
+- Domain-specific knowledge belongs in project-local homes (wiki, checklists, project-created skills). If no local home exists, ask the user where to place it.
+- Genuinely generic improvements to external skills: record as an upstream recommendation for the user (issue/PR), never edit directly.
+- When you ask the user about an unknown skill's ownership, record the verdict in `.ownership.json` so each question is asked once.
+
+**Single-responsibility pre-check** (only for targets that passed the ownership check):
+
+For proposed updates to existing skills:
+- Does the improvement align with the skill's atomic intent?
+- Or does it add a new operational domain?
+
+If scope expansion detected → propose splitting into separate skill instead of updating.
+
+### Phase 2d: Value Justification
+
+Estimate whether creating/updating a skill improves outcomes by >= 20%:
+- Assessment difficulty >= 3/5 OR knowledge gaps identified → justified
+- All difficulty <= 2/5 AND no gaps → flag as low value in proposal
+- **Frequency × cost heuristic (new):** Read `Re-use Score` (high=3, medium=2, low=1) and `Time Cost` from report/assessment; prioritize `frequency × cost` — a `high` re-use gap that cost 60m and recurs ≥2 times outranks a singleton `low` gap even if its difficulty was 5/5
+
+### Phase 2e: Context Budget Impact
+
+Estimate Tier 1 + Tier 2 token cost of proposed skill based on similar skills. Warn if >2000 tokens in proposal.
+
+### Phase 2f: Recurring Gap Clustering (compound learning)
+
+Before proposing, cluster gaps and gotchas across ALL reports in `openspec/reports/*` (excluding `archives/`).
+
+**Primary Clusterer (Hybrid Semantic via QMD):**
+Query the project-local index (never a global or shared index) scoped to `openspec` and `references` collections:
+```bash
+qmd query $'intent: cluster recurring knowledge gaps, skills gaps, and gotchas across reports\nlex: knowledge gaps skills gaps gotchas mental model shift\nvec: recurring difficulties, surprises, and lessons learned from past changes' --json -n 20 -c openspec -c references
+```
+Retrieve evidence for clustered items via `qmd multi-get "<docids>" --json`. Clusters MUST carry `qmd://` document IDs as evidence in the proposal. Semantic matching groups paraphrased descriptions of the same underlying obstacle even when distinct keywords were used.
+
+**Loud Fallback (Keyword Grep):**
+If the QMD daemon is unreachable or the index is unhealthy (`qmd status` fails):
+```bash
+# Loud fallback: note "qmd unavailable, grep fallback" in proposal
+for f in openspec/reports/*/report.md openspec/reports/*/assessment.md; do [ -f "$f" ] && echo "== $f ==" && grep -E "Knowledge gaps|Skills gaps|Concrete Gotcha|Before \(old|After \(new|Re-use Score|Time Cost" "$f" | head -n 20; done
+```
+Note `qmd unavailable, grep fallback` explicitly in the proposal's Analysis section.
+
+Group recurring findings by topic/keyword and count occurrences. Prioritize a cluster that recurs in ≥2 reports over a singleton, even if the singleton's difficulty was higher. Record the cluster table (topic/keyword → count → representative gap → `qmd://` evidence) in the proposal's Analysis section; this drives `Deferred:` decisions in Phase 5.
+
+**Dashboard generation (human curation view):** After clustering, write/overwrite `openspec/reports/dashboard.md` (never archived, never auto-loaded at agent startup):
+```bash
+# Header: generated at $(date -u +"%Y-%m-%dT%H:%M:%SZ") from N reports
+# Table: keyword | count | avg Time Cost | avg Re-use (high=3/med=2/low=1) | owning skill | m  sorted by frequency×cost desc
+# Source: grep Re-use Score + Time Cost + keyword + owning skill from clustered reports + benchmark.json m
+# If no reports, write: No reports yet — run /opsx-report after a hard task
+```
+Header `generated at <timestamp> from N reports`; table sorted `frequency × cost` desc (count × Re-use weight × avg Time Cost). Overwrite on each learn run; human reads it to curate manual reports.
+
+**Lifecycle check (prune/merge/split):** After clustering, also evaluate:
+- **Prune:** If a skill's usage count is 0 in last 10 reports OR its `benchmark.json` `behavioral.m < 0.2`, mark `Prune: <skill> — 0/10 or low m`
+- **Merge:** If ≥3 shared gaps under same keyword across 2 skills, mark `Merge: <target> ← <a> + <b> — shared keyword`
+- **Split:** If a skill's description would need `and`, mark `Split: <skill> → <a> + <b> — single-responsibility`
+Each emits one-path `What Changes: Remove project/skills/<skill>/` or `Merge: ...` with `Deferred:` for rejected lifecycle candidates.
+
+### Phase 3: Tool Type Determination
+
+See [references/tool-type-detection.md](references/tool-type-detection.md) for full detection matrix.
+
+### Phase 4: Conflict Resolution
+
+See [references/conflict-handling.md](references/conflict-handling.md) for merging strategies.
+
+### Phase 5: OpenSpec Proposal Generation
+
+Generate proposal including:
+- What to build + why (from report + assessment)
+- Suggested Triggers section (from Phase 2b) — MUST use the exact frontmatter field names `positive_triggers` and `anti_triggers` as list headers, with each value formatted for verbatim transfer into a skill's frontmatter (no prose labels like "Positive:" or "Negative:")
+- **Contrast and Anti-example hints (from report's Mental Model Shift / Concrete Gotcha):** Carry `Contrast: Before X → After Y` (1–2 lines) and `Anti-example: Do NOT: <before code> → Do: <after code>` verbatim into What Changes so `create-skill` can generate contrast tables and anti-examples as first-class content
+- **Layer-aware decision note:** State `Layer: 1 (always) vs 2 (on-demand skill) vs 3 (gate)` — for `Re-use Score: high` + `Time Cost >30m` + recurring cluster, suggest `Layer 1/3` promotion (e.g., `guardrails` skill or `AGENTS.md` Must-read pointer); otherwise `Layer 2` new/updated skill; no gate is implemented in this change, only the hint
+- **Lifecycle What Changes (when applicable):** Emit `What Changes: Remove project/skills/<skill>/` for prune, `What Changes: Merge project/skills/<target>/ ← <a> + <b>` for merge, or `Split` with two one-path creates; each with `Impact: evals + manifest updated` and `Deferred:` for rejected lifecycle candidates; cap 8 enforced here (see Gotchas)
+- Value Justification section (from Phase 2d, now including frequency × cost)
+- Collision warnings (from Phase 2a)
+- Context budget impact (from Phase 2e)
+- Clustering summary (from Phase 2f) — keyword → count → representative gap
+- **Dashboard citation (MANDATORY when lifecycle or create):** Each `create`/`prune`/`merge`/`split` in `What Changes` MUST cite `Source: dashboard.md#<keyword> — <count>× <Re-use> <time> (avg)` with verification path `openspec/reports/dashboard.md` — e.g., `Source: dashboard.md#lifetime — 4× high 45m avg`
+- Evals impact statement (MANDATORY when the proposal modifies an existing skill): state whether `evals/evals.json` changes; if triggers are added or altered, include at least one matching eval entry in Impact. No trigger changes → state that existing evals remain valid.
+- Deferred signals line (when the source report/assessment contains more improvement candidates than the proposal adopts): name each unadopted candidate with a one-line reason, so deferral is explicit rather than silent
+
+**One-path rule**: every What Changes and Impact item names exactly ONE concrete target file path. Either/or targets ("X or Y") are prohibited — resolve the choice during design, before tasks are written. Task verify clauses must reference the same single path.
+
+**OpenSpec CLI Contract & Store Forwarding:**
+- Scaffold new changes with `openspec new change "<name>"` (forwarding `--store <id>` if selected). Never create change directories by hand.
+- Forward selected `--store <id>` on applicable commands (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`); keep sticky; nearest-root if unselected. Other commands run unflagged.
+- Failure envelope: Parse stdout as single JSON payload; stderr carries prose/spinners/store banner (never parse stderr as JSON). On exit 1, parse `status: [diagnostic]` array (`severity`, `code`, `message`, `fix`). Exit 130 = prompt cancelled.
+- Payload casing: Workflow payloads use `camelCase`; store payloads use `snake_case` (`root.store_id` always `snake_case`).
+- Archive delegation: Follow-on change archiving delegates to `openspec archive --json` (`archivedAs`, `specsUpdated`, `totals`, `warnings`). Never hand `mv` change directories or hand-merge delta specs into main specs.
+
+The proposal instructs the AI agent to invoke create-skill during `/opsx-apply`.
+
+### Phase 6: Archive Processed Reports
+
+```bash
+mkdir -p ./openspec/reports/archives
+mv ./openspec/reports/<name> ./openspec/reports/archives/
+# dashboard.md never moves — it stays at openspec/reports/dashboard.md (human curation view, not a report)
+```
+Note: Only processed reports are moved via `mv`. OpenSpec changes MUST be archived via `openspec archive --json`, never by hand `mv`.
+
+### Phase 7: Display Summary
+
+Report count, proposal count, archive count, next steps.
+
+## Gotchas
+
+- **Collision detection prevents dilution**: Two skills with similar descriptions reduce routing confidence for both.
+- **Trigger metadata saves Discovery time**: Pre-filling triggers from assessment data gives create-skill a head start.
+- **Low-value skills waste context**: If difficulty <= 2/5 and no gaps, don't create a skill — the agent handles it fine already.
+- **Context budget matters**: Every skill costs tokens on every activation. Estimate before creating.
+- **Single-responsibility**: If improvement adds new domain to existing skill, split instead of updating.
+- **Deferred is explicit (clustering-driven):** When clustering finds 4 candidates and proposal adopts 2, the remaining 2 MUST appear under `Deferred:` with one-line reasons — populated from Phase 2f cluster table, not silently dropped.
+- **Lifecycle: prune/merge/split:** `Prune` when 0/10 or `m<0.2`, `Merge` when ≥3 shared gaps same keyword, `Split` when description needs `and` — emit one-path `What Changes` with `Deferred:` for rejected
+- **Cap 8: create must pair with prune/merge at cap:** When 8 skills exist, any `create` proposal MUST also include a `prune` or `merge` in same proposal; never silently exceed cap
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No reports found | Suggest `/opsx-report` |
+| Report missing assessment.md | Process report.md only |
+| Invalid proposal generation | Log error, continue |
+| Archive move fails | Log error, leave in place |
+
+## Reference Files
+
+- `references/report-analysis.md` — How to parse reports
+- `references/skill-quality.md` — Quality criteria
+- `references/improvement-patterns.md` — Common improvement types
+- `references/evaluation-methodology.md` — Eval framework
+- `references/tool-type-detection.md` — Full detection matrix
+- `references/conflict-handling.md` — Merging strategies
+- `references/examples.md` — Worked examples

package/skills/openspec-learn/evals/benchmark.json

@@ -0,0 +1,44 @@
+{
+  "skill": "opsx-learn",
+  "generated": {
+    "by": "process:compute-benchmark/1.0",
+    "at": "2026-08-23T12:42:46Z"
+  },
+  "stage": "behavioral",
+  "structural": {
+    "validate_structure": {
+      "pass": true,
+      "warnings": [
+        "Missing scripts/ directory",
+        "Missing assets/ directory"
+      ]
+    },
+    "validate_routing": {
+      "checks_total": 6,
+      "positive_triggers": 3,
+      "anti_triggers": 2,
+      "description_body_alignment": "10/10 description keywords found in body (100% alignment)",
+      "single_responsibility": true
+    },
+    "evals": {
+      "count": 3,
+      "assertions": 9,
+      "anti_trigger_coverage": true
+    }
+  },
+  "behavioral_dxm": "1×0.27",
+  "ship_gate": {
+    "criterion": "d = +1 and m >= 0.2",
+    "applies_to": "behavioral stage"
+  },
+  "behavioral": {
+    "at": "2026-09-12T09:38:54.002Z",
+    "evals": 4,
+    "assertions": 11,
+    "baseline": 0.5455,
+    "with_skill": 0.8182,
+    "d": 1,
+    "m": 0.2727,
+    "ship": "pass"
+  }
+}

package/skills/openspec-learn/evals/evals.json

@@ -0,0 +1,48 @@
+{
+  "skill_name": "opsx-learn",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Analyze all reports in ./openspec/reports/ and generate OpenSpec proposals for improvements.",
+      "expected_output": "System scans ./openspec/reports/, processes each report, determines tool type (skill/prompt/combo), and generates OpenSpec proposals in ./openspec/changes/.",
+      "files": [],
+      "assertions": [
+        "Report directory exists at ./openspec/reports/",
+        "At least one proposal generated in ./openspec/changes/",
+        "Each proposal has proposal.md, specs/, design.md, tasks.md",
+        "Processed reports moved to ./openspec/reports/archives/"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Analyze the add-central-datastore report and generate a proposal.",
+      "expected_output": "System processes single report, determines it's a database skill, generates proposal for database-schema skill.",
+      "files": [],
+      "assertions": [
+        "Single report processed from ./openspec/reports/add-central-datastore/",
+        "Proposal generated for database-schema skill",
+        "Proposal contains relevant specs from report"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "What reports are available for analysis?",
+      "expected_output": "System lists available reports in ./openspec/reports/ directory.",
+      "files": [],
+      "assertions": [
+        "List of available reports displayed",
+        "Reports in ./openspec/reports/archives/ not shown"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "I want to propose a new change to add caching to our API service.",
+      "expected_output": "Agent does NOT activate openspec-learn. This is a new change proposal request handled by openspec-propose; openspec-learn only analyzes existing reports to plan skill improvements.",
+      "files": [],
+      "assertions": [
+        "Anti-trigger fires: request routes to openspec-propose, not openspec-learn",
+        "No report scanning or skill learning workflow executed"
+      ]
+    }
+  ]
+}

package/skills/openspec-learn/evals/retrieval-bench.json

@@ -0,0 +1,27 @@
+{
+  "description": "Retrieval benchmark for openspec-learn clustering queries",
+  "version": 1,
+  "collection": "openspec",
+  "queries": [
+    {
+      "id": "cluster-baseline-exact",
+      "query": "submodule pointer sync",
+      "type": "exact",
+      "description": "Exact keyword match baseline for submodule pointer sync",
+      "expected_files": [
+        "specs/submodule-pointer-sync/spec.md"
+      ],
+      "expected_in_top_k": 1
+    },
+    {
+      "id": "cluster-paraphrase-semantic",
+      "query": "intent: find the spec that owns submodule pointer freshness\nlex: submodule pointer sync gitlink\nvec: which capability requires committing the updated submodule pointer",
+      "type": "semantic",
+      "description": "Paraphrased query document retrieving submodule pointer spec without exact title match",
+      "expected_files": [
+        "specs/submodule-pointer-sync/spec.md"
+      ],
+      "expected_in_top_k": 1
+    }
+  ]
+}

package/skills/openspec-learn/references/conflict-handling.md

@@ -0,0 +1,20 @@
+# Conflict Handling
+
+When multiple reports affect same tool:
+
+1. **Collect all improvements** from each report
+2. **Merge into single proposal** with combined requirements
+3. **Deduplicate** redundant improvements
+4. **Prioritize** by assessment difficulty ratings
+5. **Note provenance** which report contributed which improvement
+
+## Example
+
+```
+Report A: "Improved csv-analyzer with better parsing"
+Report B: "Fixed csv-analyzer edge cases"
+
+System detects: Both affect csv-analyzer
+System action: Merges into single proposal
+Result: One proposal with combined improvements
+```

package/skills/openspec-learn/references/evaluation-methodology.md

@@ -0,0 +1,126 @@
+# Evaluation Methodology
+
+How to measure quality before and after improvements.
+
+## Before/After Measurement
+
+### Step 1: Baseline Measurement
+
+Before applying improvements:
+
+1. **Structural validation**:
+   ```bash
+   project/skills/create-skill/scripts/validate-structure.mjs <skill-dir>
+   ```
+   Extract: pass/fail, errors, warnings
+
+2. **Antipattern audit**:
+   ```bash
+   project/skills/create-skill/scripts/audit-antipatterns.mjs <skill-dir>
+   ```
+   Extract: pass/fail, violation count, violations
+
+3. **Content review** (manual):
+   - Description specificity: 0-10
+   - Instruction clarity: 0-10
+   - Progressive disclosure: 0-5
+   - Gotchas present: 0-5
+
+4. **Calculate baseline score**:
+   ```
+   Structural: 30 points (from validation)
+   Content: 30 points (from review)
+   Fragility: 15 points (from classification)
+   Antipatterns: 15 points (from audit)
+   Trigger: 10 points (from tests)
+   Total: 0-100
+   ```
+
+### Step 2: Apply Improvements
+
+Apply the determined improvements (see improvement-patterns.md).
+
+### Step 3: Post-Improvement Measurement
+
+After applying improvements:
+
+1. Re-run all checks from Step 1
+2. Calculate new score
+3. Calculate delta:
+   ```
+   delta = new_score - baseline_score
+   percentage = (delta / baseline_score) * 100
+   ```
+
+## Quality Delta Interpretation
+
+| Delta | Interpretation | Action |
+|-------|----------------|--------|
+| > 10% | Significant improvement | Report success |
+| 0-10% | Minor improvement | Report success, consider more |
+| 0 | Plateau | Stop iterating |
+| < 0 | Degradation | Rollback, report failure |
+
+## Rollback Procedure
+
+If quality degraded:
+
+1. **Identify what changed**: Compare before/after file states
+2. **Revert changes**: Restore previous version
+3. **Update changelog**: Add entry noting rollback
+4. **Report failure**: Explain what was tried and why it failed
+
+## Iteration Logic
+
+```
+iteration = 0
+max_iterations = 3
+
+WHILE iteration < max_iterations:
+  baseline = measure_quality()
+  apply_improvements()
+  post = measure_quality()
+  delta = post - baseline
+  
+  IF delta > 0:
+    report_success()
+    BREAK
+  ELSE IF delta == 0:
+    report_plateau()
+    BREAK
+  ELSE:
+    rollback()
+    iteration++
+    
+IF iteration == max_iterations:
+  report_max_reached()
+```
+
+## Metrics to Track
+
+| Metric | Before | After | Delta |
+|--------|--------|-------|-------|
+| Structural score | X | Y | Y-X |
+| Antipattern count | X | Y | Y-X |
+| Description length | X | Y | Y-X |
+| SKILL.md lines | X | Y | Y-X |
+| Reference count | X | Y | Y-X |
+| Script count | X | Y | Y-X |
+
+## Report Template
+
+```markdown
+## Quality Evaluation
+
+**Baseline score:** X/100
+**Post-improvement score:** Y/100
+**Delta:** +Z%
+
+### Changes
+- Structural: X → Y
+- Content: X → Y
+- Antipatterns: X → Y
+
+### Verdict
+[Success / Plateau / Failure]
+```

package/skills/openspec-learn/references/examples.md

@@ -0,0 +1,37 @@
+# Examples
+
+## Single Report Processing
+
+```bash
+/opsx-learn add-central-datastore
+```
+
+1. System finds report at `./openspec/reports/add-central-datastore/`
+2. Analyzes report.md and assessment.md
+3. Determines: database-schema skill needs improvement
+4. Generates proposal at `./openspec/changes/add-database-schema-improvements/`
+5. Moves report to `./openspec/reports/archives/`
+6. User reviews proposal with `/opsx-explore` or implements with `/opsx-apply`
+
+## Batch Processing
+
+```bash
+/opsx-learn
+```
+
+1. System scans `./openspec/reports/` for all reports (excluding archives)
+2. Processes each report sequentially
+3. Merges improvements for same tool
+4. Generates separate proposals for different tools
+5. Moves all processed reports to archives
+
+## Conflict Resolution
+
+```
+Report A: "Improved csv-analyzer with better parsing"
+Report B: "Fixed csv-analyzer edge cases"
+
+System detects: Both affect csv-analyzer
+System action: Merges into single proposal
+Result: One proposal with combined improvements
+```