mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-03-20 12:11:28 -07:00
docs: add stats dashboard design docs, plans, and knowledge base
- Stats dashboard redesign design and implementation plans - Episode detail and Anki card link design - Internal knowledge base restructure - Backlog tasks for testing, verification, and occurrence tracking
This commit is contained in:
30
docs/workflow/README.md
Normal file
30
docs/workflow/README.md
Normal file
@@ -0,0 +1,30 @@
|
||||
<!-- read_when: starting implementation, deciding whether to plan, or checking handoff expectations -->
|
||||
|
||||
# Workflow
|
||||
|
||||
Status: active
|
||||
Last verified: 2026-03-13
|
||||
Owner: Kyle Yasuda
|
||||
Read when: planning or executing nontrivial work in this repo
|
||||
|
||||
This section is the internal workflow map for contributors and agents.
|
||||
|
||||
## Read Next
|
||||
|
||||
- [Planning](./planning.md) - when to write a lightweight plan vs a full execution plan
|
||||
- [Verification](./verification.md) - maintained test/build lanes and handoff gate
|
||||
- [Release Guide](../RELEASING.md) - tagged release workflow
|
||||
|
||||
## Default Flow
|
||||
|
||||
1. Read the smallest relevant docs from `docs/`.
|
||||
2. Decide whether the work needs a written plan.
|
||||
3. Implement in small, reviewable edits.
|
||||
4. Run the cheapest sufficient verification lane.
|
||||
5. Escalate to the full maintained gate before handoff when the change is substantial.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- Internal process lives in `docs/`.
|
||||
- Public/product docs live in `docs-site/`.
|
||||
- Generated artifacts are never edited by hand.
|
||||
41
docs/workflow/planning.md
Normal file
41
docs/workflow/planning.md
Normal file
@@ -0,0 +1,41 @@
|
||||
<!-- read_when: deciding whether work needs a plan or writing one -->
|
||||
|
||||
# Planning
|
||||
|
||||
Status: active
|
||||
Last verified: 2026-03-13
|
||||
Owner: Kyle Yasuda
|
||||
Read when: the task spans multiple files, subsystems, or verification lanes
|
||||
|
||||
## Plan Types
|
||||
|
||||
- Lightweight plan: small change, a few reversible steps, minimal coordination
|
||||
- Execution plan: nontrivial feature/refactor/debugging effort with multiple phases or important decisions
|
||||
|
||||
## Use a Lightweight Plan When
|
||||
|
||||
- one subsystem
|
||||
- obvious change shape
|
||||
- low risk
|
||||
- easy to verify
|
||||
|
||||
## Use an Execution Plan When
|
||||
|
||||
- multiple subsystems or runtimes
|
||||
- architectural tradeoffs matter
|
||||
- staged verification is needed
|
||||
- the work should be resumable by another agent or human
|
||||
|
||||
## Plan Location
|
||||
|
||||
- active design and implementation docs live in `docs/plans/`
|
||||
- keep names date-prefixed and task-specific
|
||||
- remove or archive old plans deliberately; do not leave mystery artifacts
|
||||
|
||||
## Plan Contents
|
||||
|
||||
- problem / goal
|
||||
- non-goals
|
||||
- file ownership or edit scope
|
||||
- verification plan
|
||||
- decisions made during execution
|
||||
41
docs/workflow/verification.md
Normal file
41
docs/workflow/verification.md
Normal file
@@ -0,0 +1,41 @@
|
||||
<!-- read_when: choosing what tests/build steps to run before handoff -->
|
||||
|
||||
# Verification
|
||||
|
||||
Status: active
|
||||
Last verified: 2026-03-13
|
||||
Owner: Kyle Yasuda
|
||||
Read when: selecting the right verification lane for a change
|
||||
|
||||
## Default Handoff Gate
|
||||
|
||||
```bash
|
||||
bun run typecheck
|
||||
bun run test:fast
|
||||
bun run test:env
|
||||
bun run build
|
||||
bun run test:smoke:dist
|
||||
```
|
||||
|
||||
If `docs-site/` changed, also run:
|
||||
|
||||
```bash
|
||||
bun run docs:test
|
||||
bun run docs:build
|
||||
```
|
||||
|
||||
## Cheap-First Lane Selection
|
||||
|
||||
- Docs-only boundary/content changes: `bun run docs:test`, `bun run docs:build`
|
||||
- Internal KB / `AGENTS.md` changes: `bun run test:docs:kb`
|
||||
- Config/schema/defaults: `bun run test:config`, then `bun run generate:config-example` if template/defaults changed
|
||||
- Launcher/plugin: `bun run test:launcher` or `bun run test:env`
|
||||
- Runtime-compat / compiled behavior: `bun run test:runtime:compat`
|
||||
- Deep/local full gate: default handoff gate above
|
||||
|
||||
## Rules
|
||||
|
||||
- Capture exact failing command and error when verification breaks.
|
||||
- Prefer the cheapest sufficient lane first.
|
||||
- Escalate when the change crosses boundaries or touches release-sensitive behavior.
|
||||
- Never hand-edit `dist/launcher/subminer`; validate it through build/test flow instead.
|
||||
Reference in New Issue
Block a user