worktype

Documentation

Overview

Package worktype names the closed set of WORK CLASSES the project-management surfaces sort work into — the single source of truth that lets the milestone roadmap and the `fak program` report draw the same line between an ONGOING OPTIMIZATION PROGRAM and a DISCRETE DELIVERABLE EPIC.

The distinction this package exists to make. The fleet's planning surfaces (internal/milestonereport, internal/cadencereport) historically folded every tracked epic into one undifferentiated "roadmap" measured by child-completion percent. That is a category error for the two long-horizon programs at the core of fak's value:

• KERNEL OPTIMIZATION — pushing decode/prefill throughput and numeric parity toward and past SOTA on each model x backend cell. It is never "done": there is always a faster kernel. Its honest measure is a FRONTIER (the best number witnessed so far) and a TREND (is the frontier still advancing?), not a percent-complete bar. A "60% complete" line on kernel-opt is meaningless.
• CACHE OPTIMIZATION — the agent-memory-and-reuse value-add: multi-agent KV reuse, O(1) bounded context + queryable history, provider-cache preservation, addressable KV deletion. Like kernel-opt it is an ongoing frontier program with its own operating spine (docs/CACHE-FRONTIER-OPERATING-PLAN.md) and its own evidence ledgers (the cache-value roll-up + the cache-frontier review ledger), NOT a deliverable that completes.
• HUMAN OPERATOR EFFECTIVENESS — keeping fak understandable and steerable as the agent fleet, CLI surface, refusal vocabulary, and background loops grow. Its honest measure is a FRONTIER (operator brief, heaviness pressure, source coherence, change compression), not a done bar.

A DISCRETE EPIC, by contrast, is a deliverable with a definition of done — the native agent harness, release-at-agentic-speed, support-maturity disambiguation. Child-completion percent IS the right lens for those: they converge on 100% and then close.

Keeping the two classes apart in the planning surfaces stops an ongoing program from being mis-read as "stalled at 40%" (it has no 100%) and stops a discrete epic from hiding inside a frontier trend. This package is the one table that names the classes, defines them, and classifies an epic by number — so both reports sort the same way and a reclassification is a one-line edit here, not a scattered set of magic numbers across two report packages.

The package is pure and stdlib-only (tier 1): it imports nothing internal and reads no disk, so the report packages can fold it without a process or a repo.

Index

• Constants
• Variables
• func DeclaredEpics() []int
• type Class
  • func ClassifyEpic(number int) Class
  • func (c Class) Definition() string
  • func (c Class) Label() string
  • func (c Class) Ongoing() bool
• type Pattern
• type PatternCatalog
  • func ParsePatternCatalog(b []byte) (PatternCatalog, error)
  • func SeedPatternCatalog() PatternCatalog
  • func (c PatternCatalog) DeterministicJSON() ([]byte, error)
  • func (c PatternCatalog) Validate() error
• type Program
  • func ProgramFor(c Class) (Program, bool)
• type Provenance
• type Subpattern

Constants

const PatternCatalogSchema = "fak.workpattern-catalog/1"

PatternCatalogSchema is the stable machine contract for coding-workload patterns.

Variables

var Programs = []Class{KernelOptimization, CacheOptimization, HumanOperatorEffectiveness}

Programs is the ordered list of the ongoing-program classes. The `fak program` report iterates this so a new program is added by extending this slice (and the registry below), never by editing the report loop.

Functions

func DeclaredEpics

func DeclaredEpics() []int

DeclaredEpics returns the epic numbers explicitly declared as ongoing programs, in ascending order. Exported so a test (or a report) can assert the declared set without reaching into the unexported map.

Types

type Class

type Class string

Class is the closed work-class vocabulary. A value outside this set is a bug, not a lower-priority bucket — the same closed-vocabulary discipline the kernel applies to a refusal reason or a maturity rung.

const (
	// KernelOptimization is the ONGOING throughput/parity program over the
	// model x backend grid. Measured by a frontier + trend, never a completion %.
	KernelOptimization Class = "kernel-optimization"
	// CacheOptimization is the ONGOING agent-memory-and-reuse program (the cache
	// frontier). Measured by a frontier + trend, never a completion %.
	CacheOptimization Class = "cache-optimization"
	// HumanOperatorEffectiveness is the ONGOING human-steerability program:
	// attention, learning pace, source coherence, change compression, and surface pressure.
	HumanOperatorEffectiveness Class = "human-operator-effectiveness"
	// DiscreteEpic is a deliverable with a definition of done — measured by
	// child-issue completion percent, which converges on 100% and then closes.
	DiscreteEpic Class = "discrete-epic"
)

func ClassifyEpic

func ClassifyEpic(number int) Class

ClassifyEpic returns the work class for a tracked epic number. An epic not in the declared map is a DiscreteEpic (the conservative default).

func (Class) Definition

func (c Class) Definition() string

Definition is the one-line definition of a class — the written distinction the disambiguation discipline owes for any confusable concept. Rendered in the report header so an operator reading the split sees WHY a program is not on a % bar.

func (Class) Label

func (c Class) Label() string

Label is the short human label for a class, for a render line or a Slack card.

func (Class) Ongoing

func (c Class) Ongoing() bool

Ongoing reports whether a class is an ongoing optimization PROGRAM (frontier + trend, never "done") rather than a discrete deliverable. It is the one predicate the reports branch on to decide whether a completion percent is meaningful for a row. An unknown class is treated as discrete (the conservative default: show the percent, do not invent a frontier we cannot measure).

type Pattern

type Pattern struct {
	ID          string     `json:"id"`
	Name        string     `json:"name"`
	Intent      string     `json:"intent"`
	Axes        []string   `json:"axes"`
	Aliases     []string   `json:"aliases,omitempty"`
	IncludeWhen string     `json:"include_when"`
	ExcludeWhen string     `json:"exclude_when"`
	Provenance  Provenance `json:"provenance"`
	Evidence    []string   `json:"evidence"`
	Subpatterns []string   `json:"subpatterns"`
}

Pattern describes a goal-shaped coding workload. Subpatterns are reusable moves that may compose into more than one Pattern.

type PatternCatalog

type PatternCatalog struct {
	Schema      string       `json:"schema"`
	Version     string       `json:"version"`
	Patterns    []Pattern    `json:"patterns"`
	Subpatterns []Subpattern `json:"subpatterns"`
}

func ParsePatternCatalog

func ParsePatternCatalog(b []byte) (PatternCatalog, error)

func SeedPatternCatalog

func SeedPatternCatalog() PatternCatalog

func (PatternCatalog) DeterministicJSON

func (c PatternCatalog) DeterministicJSON() ([]byte, error)

func (PatternCatalog) Validate

func (c PatternCatalog) Validate() error

type Program

type Program struct {
	// Class is the work class (KernelOptimization | CacheOptimization).
	Class Class
	// TrackLabel is the GitHub label whose issues belong to this program (the same
	// label the milestone roadmap can resolve children by). Empty when the program
	// is tracked by epic membership alone.
	TrackLabel string
	// OperatingDoc is the repo-relative canonical operating plan for the program —
	// the page that defines its frontier and its decision fences.
	OperatingDoc string
	// Blurb is a one-line description of the program's product outcome.
	Blurb string
}

Program is one ongoing-program definition: its class, the GitHub track label that scopes its work, and the canonical doc that operates it. The reports read this to route an epic and to point an operator at the program's operating spine.

func ProgramFor

func ProgramFor(c Class) (Program, bool)

ProgramFor returns the program metadata for an ongoing-program class, and ok=false for a class that is not an ongoing program (DiscreteEpic or an unknown value).

type Provenance

type Provenance string

Provenance distinguishes established terminology from local synthesis.

const (
	ProvenanceBorrowed  Provenance = "borrowed"
	ProvenanceAdapted   Provenance = "adapted"
	ProvenanceSynthesis Provenance = "new-synthesis"
)

type Subpattern

type Subpattern struct {
	ID          string     `json:"id"`
	Name        string     `json:"name"`
	Intent      string     `json:"intent"`
	Axes        []string   `json:"axes"`
	Aliases     []string   `json:"aliases,omitempty"`
	IncludeWhen string     `json:"include_when"`
	ExcludeWhen string     `json:"exclude_when"`
	Provenance  Provenance `json:"provenance"`
	Evidence    []string   `json:"evidence"`
	Composes    []string   `json:"composes,omitempty"`
}