mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-03-20 12:11:28 -07:00
sudacode
ee95e86ad5
- 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
139 lines
4.6 KiB
Markdown
139 lines
4.6 KiB
Markdown
# Internal Knowledge Base Restructure Implementation Plan
|
|
|
|
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
|
**Goal:** Turn `AGENTS.md` into a compact table of contents, establish `docs/` as the internal system of record, keep `docs-site/` user-facing, and enforce the split with tests/CI.
|
|
|
|
**Architecture:** Create a small internal knowledge-base hierarchy under `docs/`, migrate canonical contributor/agent guidance into it, and wire a repo-level verification test that checks required docs, metadata, and boundary rules. Keep public docs in `docs-site/` and update them to reference internal docs rather than acting as the source of truth themselves.
|
|
|
|
**Tech Stack:** Markdown docs, Bun test runner, existing GitHub Actions CI
|
|
|
|
---
|
|
|
|
### Task 1: Add the internal KB entrypoints
|
|
|
|
**Files:**
|
|
- Create: `docs/README.md`
|
|
- Create: `docs/architecture/README.md`
|
|
- Create: `docs/architecture/domains.md`
|
|
- Create: `docs/architecture/layering.md`
|
|
- Create: `docs/knowledge-base/README.md`
|
|
- Create: `docs/knowledge-base/core-beliefs.md`
|
|
- Create: `docs/knowledge-base/catalog.md`
|
|
- Create: `docs/knowledge-base/quality.md`
|
|
- Create: `docs/workflow/README.md`
|
|
- Create: `docs/workflow/planning.md`
|
|
- Create: `docs/workflow/verification.md`
|
|
|
|
**Step 1: Write the KB home page**
|
|
|
|
Add `docs/README.md` with navigation to architecture, workflow, knowledge-base maintenance, release docs, and active plans.
|
|
|
|
**Step 2: Add architecture pages**
|
|
|
|
Create the architecture index plus focused `domains.md` and `layering.md` pages that summarize runtime ownership and dependency boundaries from the existing architecture doc.
|
|
|
|
**Step 3: Add knowledge-base pages**
|
|
|
|
Create the knowledge-base index, core beliefs, catalog, and quality pages with explicit metadata fields and short maintenance guidance.
|
|
|
|
**Step 4: Add workflow pages**
|
|
|
|
Create workflow index, planning guide, and verification guide with the current maintained Bun commands and lane-selection guidance.
|
|
|
|
**Step 5: Review cross-links**
|
|
|
|
Read the new docs and confirm every page links back to at least one parent/index page.
|
|
|
|
### Task 2: Rewrite `AGENTS.md` as a compact map
|
|
|
|
**Files:**
|
|
- Modify: `AGENTS.md`
|
|
|
|
**Step 1: Replace encyclopedia-style content with a compact map**
|
|
|
|
Keep only the minimum operational guidance needed in injected context:
|
|
- quick start
|
|
- internal source-of-truth pointers
|
|
- build/test gate
|
|
- generated/sensitive file notes
|
|
- release pointer
|
|
- backlog note
|
|
|
|
**Step 2: Add direct links to the new KB entrypoints**
|
|
|
|
Point `AGENTS.md` at:
|
|
- `docs/README.md`
|
|
- `docs/architecture/README.md`
|
|
- `docs/workflow/README.md`
|
|
- `docs/workflow/verification.md`
|
|
- `docs/knowledge-base/README.md`
|
|
- `docs/RELEASING.md`
|
|
|
|
**Step 3: Keep the file intentionally short**
|
|
|
|
Target roughly 100 lines and avoid moving deep details back into `AGENTS.md`.
|
|
|
|
### Task 3: Re-boundary `docs-site/`
|
|
|
|
**Files:**
|
|
- Modify: `docs-site/development.md`
|
|
- Modify: `docs-site/architecture.md`
|
|
- Modify: `docs-site/README.md`
|
|
|
|
**Step 1: Update contributor-facing docs**
|
|
|
|
Keep build/run/testing instructions, but stop presenting `docs-site/*` pages as canonical internal architecture/workflow references.
|
|
|
|
**Step 2: Add explicit internal-doc pointers**
|
|
|
|
Link readers to `docs/README.md` and the new internal architecture/workflow pages for deep contributor guidance.
|
|
|
|
**Step 3: Preserve public-doc tone**
|
|
|
|
Ensure the `docs-site/` pages remain user/contributor-facing and do not become the internal KB themselves.
|
|
|
|
### Task 4: Add mechanical enforcement
|
|
|
|
**Files:**
|
|
- Create: `scripts/docs-knowledge-base.test.ts`
|
|
- Modify: `package.json`
|
|
- Modify: `.github/workflows/ci.yml`
|
|
|
|
**Step 1: Write a repo-level docs KB test**
|
|
|
|
Assert:
|
|
- required docs exist
|
|
- metadata fields exist on internal docs
|
|
- `AGENTS.md` links to internal KB entrypoints
|
|
- `AGENTS.md` stays under the line cap
|
|
- `docs-site/development.md` and `docs-site/architecture.md` point to `docs/`
|
|
|
|
**Step 2: Wire the test into package scripts**
|
|
|
|
Add a script for the KB test and include it in an existing maintained verification lane.
|
|
|
|
**Step 3: Ensure CI exercises the check**
|
|
|
|
Make sure the CI path that runs the maintained test lane catches KB regressions.
|
|
|
|
### Task 5: Verify and hand off
|
|
|
|
**Files:**
|
|
- Modify: any files above if verification reveals drift
|
|
|
|
**Step 1: Run targeted docs verification**
|
|
|
|
Run:
|
|
- `bun run docs:test`
|
|
- `bun run test:fast`
|
|
- `bun run docs:build`
|
|
|
|
**Step 2: Fix drift found by tests**
|
|
|
|
If any assertions fail, update the docs or test expectations so the enforced model matches the intended structure.
|
|
|
|
**Step 3: Summarize outcome**
|
|
|
|
Report the new internal KB entrypoints, the `AGENTS.md` table-of-contents rewrite, enforcement coverage, verification results, and any skipped items.
|