Add a structured learnings tool and data model

sam commented

2026-04-01 19:12:27 +00:00

Member

Summary

Add a focused AMCS learnings capability for storing structured development learnings as first-class records instead of burying them inside generic thoughts or markdown notes.

Why

This is still a useful product feature even though AMCS already has thoughts, skills, guardrails, and tool annotations. A learnings model would cover a different use case: durable, queryable lessons and corrections that can later be reviewed, resolved, or promoted into reusable guidance.

Important scope note

Keep v1 narrow. This issue should not try to solve every future promotion or workflow-automation use case in one shot.

Recommended v1 scope

Add a structured learnings record with:

stable learning ID
category
area
status
priority
summary
details/body
optional related project / thought / skill references
created/updated timestamps

Add a tool surface for:

create learning
search/list learnings
get learning
update learning status and fields

Suggested v1 enums

Area

frontend
backend
infra
tests
docs
config
other

Status

pending
in_progress
resolved
wont_fix
promoted
promoted_to_skill

Additional v1 guidance

A learning is a curated, durable lesson distinct from raw thoughts or generic notes.
Each learning should preserve provenance where possible via source metadata (for example source type and source reference).
v1 should support lightweight operational triage, including whether the learning is verified and whether follow-up action is required.
Tag support should exist in addition to fixed enums so domain-specific clustering does not overload area.

Suggested additional fields

tags
source_type
source_ref
confidence or evidence_level (hypothesis, observed, verified)
action_required or actionability
optional reviewed_by, reviewed_at
optional relationship fields like duplicate_of_learning_id or supersedes_learning_id

Out of scope for v1

full workflow automation for promotion targets
automatic extraction into skills
large markdown-rendering/reporting flows
trying to replace generic thoughts entirely

Acceptance criteria

DB schema exists for structured learning records
CRUD/search tool surface exists for learnings
Search/filter works across category, area, status, and text
Learnings can be referenced by a stable ID
Optional links to project, thought, or skill can be stored cleanly
Tool responses are simple and agent-friendly
Free-text search works across summary and details
Filters support project, category, area, status, priority, and tags
A learning can record provenance/source cleanly
A learning can represent whether it is verified vs provisional
The model cleanly distinguishes curated learnings from generic thoughts

Rationale

This keeps #4 as real product work instead of a giant “build a knowledge-management universe” ticket. Future promotion/reporting workflows can be added in follow-up issues.

Why these additions help

These keep the feature narrow but more useful in practice:

provenance prevents “mystery lessons” with no source
verified vs provisional prevents guesses from looking authoritative
tags prevent overloading area
light relationship support prevents duplicate or superseded learnings from piling up unchecked

## Summary Add a focused AMCS learnings capability for storing structured development learnings as first-class records instead of burying them inside generic thoughts or markdown notes. ## Why This is still a useful product feature even though AMCS already has thoughts, skills, guardrails, and tool annotations. A learnings model would cover a different use case: durable, queryable lessons and corrections that can later be reviewed, resolved, or promoted into reusable guidance. ## Important scope note Keep v1 narrow. This issue should **not** try to solve every future promotion or workflow-automation use case in one shot. ## Recommended v1 scope Add a structured learnings record with: - stable learning ID - category - area - status - priority - summary - details/body - optional related project / thought / skill references - created/updated timestamps Add a tool surface for: - create learning - search/list learnings - get learning - update learning status and fields ## Suggested v1 enums ### Category - `correction` - `insight` - `knowledge_gap` - `best_practice` ### Area - `frontend` - `backend` - `infra` - `tests` - `docs` - `config` - `other` ### Status - `pending` - `in_progress` - `resolved` - `wont_fix` - `promoted` - `promoted_to_skill` ## Additional v1 guidance - A learning is a curated, durable lesson distinct from raw thoughts or generic notes. - Each learning should preserve provenance where possible via source metadata (for example source type and source reference). - v1 should support lightweight operational triage, including whether the learning is verified and whether follow-up action is required. - Tag support should exist in addition to fixed enums so domain-specific clustering does not overload `area`. ## Suggested additional fields - `tags` - `source_type` - `source_ref` - `confidence` or `evidence_level` (`hypothesis`, `observed`, `verified`) - `action_required` or `actionability` - optional `reviewed_by`, `reviewed_at` - optional relationship fields like `duplicate_of_learning_id` or `supersedes_learning_id` ## Out of scope for v1 - full workflow automation for promotion targets - automatic extraction into skills - large markdown-rendering/reporting flows - trying to replace generic thoughts entirely ## Acceptance criteria - [ ] DB schema exists for structured learning records - [ ] CRUD/search tool surface exists for learnings - [ ] Search/filter works across category, area, status, and text - [ ] Learnings can be referenced by a stable ID - [ ] Optional links to project, thought, or skill can be stored cleanly - [ ] Tool responses are simple and agent-friendly - [ ] Free-text search works across summary and details - [ ] Filters support project, category, area, status, priority, and tags - [ ] A learning can record provenance/source cleanly - [ ] A learning can represent whether it is verified vs provisional - [ ] The model cleanly distinguishes curated learnings from generic thoughts ## Rationale This keeps #4 as real product work instead of a giant “build a knowledge-management universe” ticket. Future promotion/reporting workflows can be added in follow-up issues. ## Why these additions help These keep the feature narrow but more useful in practice: - provenance prevents “mystery lessons” with no source - verified vs provisional prevents guesses from looking authoritative - tags prevent overloading `area` - light relationship support prevents duplicate or superseded learnings from piling up unchecked