learning

Documentation

Overview

Package learning 管理 retro learnings 的儲存與生命週期。 learnings 是跨 feature 累積的開發教訓，由 CLI 全權讀寫（runner 不直接碰）， 透過 prompt 層注入到後續 feature 的各 role，藉以迭代 prompt 品質。

Index

• Constants
• func CommitIfDirty(root, dotDir string)
• func IsValidCategory(c Category) bool
• func JaccardSimilarity(a, b map[string]bool) float64
• type Category
  • func CategoriesForRole(role string) []Category
  • func ValidCategories() []Category
• type ConsolidateAction
• type ConsolidateResult
• type Entry
• type RetroFile
• type RetroLearning
  • func ParseRetroFile(path string) ([]RetroLearning, error)
  • func ParseRoleLearningsFile(path string) (string, []RetroLearning, error)
• type RoleLearningsFile
• type Status
• type Store
  • func LoadStore(path string) (Store, error)
  • func (s *Store) ActiveEntries() []Entry
  • func (s *Store) ApplyConsolidation(actions []ConsolidateAction) (int, int)
  • func (s *Store) CandidateEntries() []Entry
  • func (s *Store) FindSimilar(content string) *Entry
  • func (s *Store) Harvest(featureID, sourceRole string, learnings []RetroLearning) int
  • func (s *Store) MarkCandidatesStale(maxIdleDays int) int
  • func (s *Store) MarkIneffective() int
  • func (s *Store) MarkStale(staleDays int)
  • func (s *Store) Promote(id string) error
  • func (s *Store) PromoteCandidates(ids []string)
  • func (s *Store) Prune() int
  • func (s *Store) Remove(id string) error
  • func (s *Store) Save(path string) error
  • func (s *Store) UpdateUsage(ids []string)

Constants

const (
	// DefaultStaleDays 是判定 learning 過期的天數門檻。
	DefaultStaleDays = 90
	// DefaultCandidateMaxIdleDays 是判定「從未使用的 candidate」老化為 stale 的預設天數門檻。
	DefaultCandidateMaxIdleDays = 30
	// MaxActiveEntries 是 active learnings 的軟上限，超過只 warn 不自動刪。
	MaxActiveEntries = 100
	// ConsolidateThreshold 是觸發 AI consolidate 的 active 條目門檻。
	ConsolidateThreshold = 30
	// FuzzyDupThreshold 是判定 learning 語意重複的 Jaccard 相似度門檻。
	FuzzyDupThreshold = 0.7
)

Functions

func CommitIfDirty

func CommitIfDirty(root, dotDir string)

CommitIfDirty 檢查 learnings.json 是否有未 commit 的變更，若有則自動 git add + commit。 root 為 git repo 根目錄，dotDir 為 .4x/ 目錄的絕對路徑。

func IsValidCategory

func IsValidCategory(c Category) bool

IsValidCategory 檢查 category 是否在白名單中。

func JaccardSimilarity

func JaccardSimilarity(a, b map[string]bool) float64

JaccardSimilarity 計算兩個詞集的 Jaccard 相似度 = |交集| / |聯集|。

Types

type Category

type Category string

Category 是 learning 的分類，限定為固定白名單以利 CLI 過濾與 role 對應。

const (
	CategoryDesign      Category = "design"
	CategoryCodeQuality Category = "code-quality"
	CategoryTesting     Category = "testing"
	CategoryReview      Category = "review"
	CategoryTooling     Category = "tooling"
	CategoryProcess     Category = "process"
	CategoryOps         Category = "ops"
)

func CategoriesForRole

func CategoriesForRole(role string) []Category

CategoriesForRole 回傳指定 role 應注入的 category 列表；未知 role 回傳 nil。

func ValidCategories

func ValidCategories() []Category

ValidCategories 回傳所有合法的 category 列舉，供 CLI 與驗證使用。

type ConsolidateAction

type ConsolidateAction struct {
	ID      string `json:"id"`
	Action  string `json:"action"`
	MergeID string `json:"merge_into,omitempty"`
	Content string `json:"merged_content,omitempty"`
	Reason  string `json:"reason"`
}

ConsolidateAction 是 AI 對單一 learning 的處理決策。

type ConsolidateResult

type ConsolidateResult struct {
	Actions []ConsolidateAction `json:"actions"`
}

ConsolidateResult 是 consolidate runner 的輸出結構。

type Entry

type Entry struct {
	ID            string    `json:"id"`
	SourceFeature string    `json:"source_feature"`
	SourceRole    string    `json:"source_role,omitempty"`
	Category      Category  `json:"category"`
	Content       string    `json:"content"`
	CreatedAt     time.Time `json:"created_at"`
	ActivatedAt   time.Time `json:"activated_at,omitempty"`
	LastUsed      time.Time `json:"last_used,omitempty"`
	UsedCount     int       `json:"used_count"`
	Status        Status    `json:"status"`
	Ineffective   bool      `json:"ineffective,omitempty"`
}

Entry 是 learnings.json 中的一個條目，含完整 metadata。

type RetroFile

type RetroFile struct {
	Learnings []RetroLearning `json:"learnings"`
}

RetroFile 是 .4x/{feature-id}/retro-learnings.json 的結構。

type RetroLearning

type RetroLearning struct {
	Category Category `json:"category"`
	Content  string   `json:"content"`
}

RetroLearning 是 Acceptor 產出的單一 learning（不含 ID 與 metadata）。

func ParseRetroFile

func ParseRetroFile(path string) ([]RetroLearning, error)

ParseRetroFile 讀取 Acceptor 產出的 retro-learnings.json，回傳其中的 learnings 列表。

func ParseRoleLearningsFile

func ParseRoleLearningsFile(path string) (string, []RetroLearning, error)

ParseRoleLearningsFile 讀取角色產出的 role-learnings.json，回傳角色名稱與 learnings。

type RoleLearningsFile

type RoleLearningsFile struct {
	Role      string          `json:"role"`
	Learnings []RetroLearning `json:"learnings"`
}

RoleLearningsFile 是各角色在 round 目錄內產出的 role-learnings.json 結構。

type Status

type Status string

Status 是 learning 的生命週期狀態。

const (
	StatusCandidate Status = "candidate"
	StatusActive    Status = "active"
	StatusStale     Status = "stale"
	StatusPromoted  Status = "promoted"
)

type Store

type Store struct {
	Version int     `json:"version"`
	Entries []Entry `json:"entries"`
}

Store 是 .4x/learnings.json 的完整結構。

func LoadStore

func LoadStore(path string) (Store, error)

LoadStore 讀取 learnings.json；檔案不存在時回傳空 store（version=1），不視為錯誤。

func (*Store) ActiveEntries

func (s *Store) ActiveEntries() []Entry

ActiveEntries 回傳所有 status==active 且非 ineffective 的條目，保持原始順序。

func (*Store) ApplyConsolidation

func (s *Store) ApplyConsolidation(actions []ConsolidateAction) (int, int)

ApplyConsolidation 套用 AI consolidate 的結果：merge 把被合併條目標記為 stale 並更新目標條目的 content， remove 直接移除條目。回傳 (merged, removed) 數量。

func (*Store) CandidateEntries

func (s *Store) CandidateEntries() []Entry

CandidateEntries 回傳所有 status==candidate 的條目，保持原始順序。

func (*Store) FindSimilar

func (s *Store) FindSimilar(content string) *Entry

FindSimilar 在 store 既有條目中以三層比對（exact → normalized → Jaccard ≥ 0.7） 搜尋與 content 相似的條目，回傳第一個命中的 Entry 指標，未命中回傳 nil。

func (*Store) Harvest

func (s *Store) Harvest(featureID, sourceRole string, learnings []RetroLearning) int

Harvest 把 learnings 追加到 store，回傳實際新增數量。 sourceRole 標記產出來源角色（"acceptor"、"coder"、"reviewer" 等），空字串表示未知。 三層去重：(1) content 完全比對 (2) 正規化比對（大小寫/空白/標點）(3) 詞集 Jaccard ≥ 0.7。 category 不在白名單或 content 為空的條目跳過。新條目自動分配 L 序號 ID 並標記為 candidate。 fuzzy match 到 active entry 時 skip（去重）；match 到同 feature candidate 時 skip； match 到不同 feature 的 candidate 時升級該 candidate 為 active，新的不寫入。

func (*Store) MarkCandidatesStale

func (s *Store) MarkCandidatesStale(maxIdleDays int) int

MarkCandidatesStale 把「從未被使用（UsedCount==0）且 CreatedAt 超過 maxIdleDays 天」的 candidate 條目標記為 stale，回傳新標記數。maxIdleDays <= 0 時視為停用老化，直接回傳 0 不動任何條目。 只掃 status==candidate；active/promoted/既有 stale 一律不碰（見 F147 約束）。

func (*Store) MarkIneffective

func (s *Store) MarkIneffective() int

MarkIneffective 掃描所有 active 條目，滿足以下三條件的標記 Ineffective=true，回傳新標記數： 1. UsedCount >= 3 2. ActivatedAt（零值時用 CreatedAt）距今 > 30 天 3. 最近 3 個來自不同 feature 的 entries 中有同 category 的新 learning

func (*Store) MarkStale

func (s *Store) MarkStale(staleDays int)

MarkStale 掃描所有 active 條目，超過 staleDays 天未使用的標記為 stale。 判斷依據：LastUsed 非零時用 LastUsed，否則用 CreatedAt。promoted/stale 不動。

func (*Store) Promote

func (s *Store) Promote(id string) error

Promote 將指定 ID 標記為 promoted（已升級到 template/instructions，保留記錄不再注入）。

func (*Store) PromoteCandidates

func (s *Store) PromoteCandidates(ids []string)

PromoteCandidates 將指定 ID 中 status==candidate 的條目升級為 active，並設定 ActivatedAt。

func (*Store) Prune

func (s *Store) Prune() int

Prune 移除所有 stale 條目，回傳移除數量。

func (*Store) Remove

func (s *Store) Remove(id string) error

Remove 移除指定 ID 的條目。

func (*Store) Save

func (s *Store) Save(path string) error

Save 把 store 以 atomic（temp + rename）方式寫入 learnings.json。

func (*Store) UpdateUsage

func (s *Store) UpdateUsage(ids []string)

UpdateUsage 更新指定 ID 的 LastUsed 為現在、UsedCount 遞增，標示這些 learnings 被選用過。