Design Feature

OpenUsage Feature Designer

Invocation: When a user asks to design, plan, or architect a feature — OR when a proposed change touches 3+ subsystems (core, providers, TUI, config, detect, daemon, telemetry).

---

Phase 0 — Quiz (MANDATORY)

Before any design work, gather answers to ALL of these. Research the codebase yourself if the user doesn't know.

1. What problem does this solve? One sentence. What's broken or missing today?
2. Who benefits? End users, contributors, or both?
3. What subsystems are affected? List from: core types, providers, TUI, config, detect, daemon, telemetry, CLI commands.
4. What's explicitly out of scope? Name at least one thing this feature does NOT do.
5. Are there existing design docs that overlap? Check docs/*.md for related designs. If overlap exists, ask the user whether to extend or create new.
6. What's the simplest version that delivers value? Identify the MVP slice.
7. Does this change any public interfaces? (UsageProvider, UsageSnapshot, AccountConfig, config JSON schema)
8. Backward compatibility concerns? Will existing configs, stored data, or provider behavior break?

---

Phase 1 — Explore (MANDATORY)

Read these before designing. Skip only if already in context:

1. Core types: internal/core/types.go, internal/core/provider_spec.go, internal/core/widget.go
2. Affected subsystems: Read the primary files for each subsystem from Q3.
3. Existing design docs: Read any overlapping docs from docs/.
4. Related providers: If the feature changes provider behavior, read at least one provider of each affected pattern (header probing, rich API, local files, CLI).
5. Config schema: internal/config/config.go + configs/example_settings.json

After reading, summarize findings that affect the design. Don't just list files — state what you learned.

---

Phase 2 — Design

Write the design doc to docs/<FEATURE_NAME>_DESIGN.md. Use the template in references/design-template.md.

Design principles for this project

• Simplest thing that works. No abstractions for hypothetical futures.
• Additive over breaking. New fields, new types, new files. Don't restructure what works.
• Provider patterns are sacred. Don't force providers into a new pattern. If a provider needs special handling, let it be special.
• Maps and slices over deep type hierarchies. The codebase uses flat data (map[string]Metric, map[string]string) — follow that.
• Config drives behavior. Features should be configurable in settings.json. Sensible defaults, no mandatory config.
• TUI is the consumer, not the source of truth. Business logic in core/ or subsystem packages, rendering in tui/.

What NOT to do

• Don't introduce interfaces for one implementation.
• Don't add a package for fewer than 3 files.
• Don't design middleware/plugin systems — direct function calls are fine.
• Don't propose database migrations unless the feature requires persistence.
• Don't over-specify error handling — match existing patterns (fmt.Errorf("provider: action: %w", err)).

---