docs: consolidate business/ops docs + simplify the AI-config and docs estate - #441
Merged
Conversation
…le-owner truth Two exhaustive audits (2607: 31 files/3,053 lines; company layer + 2510 + workflows + OKF) measured the estate at ~40% live / ~60% stale-or-duplicated 18 days after creation. This pass fixes every contradiction of ground truth, stamps or archives everything superseded, and realigns the roadmap so its lanes arithmetically sum to the goal. Operations (2607): - Killed the phantom kanban board: the runbook's entry point told every fresh session to read a board that was gitignored, never committed, and whose binary isn't installed; cards #12-#29 were cited ~40 times with no surviving definition. backlog.md §State is now the sole card registry. - Struck two phantom Paul-gates (grooming "PENDING PAUL'S APPROVAL" + runbook "T4/T5 held") 18 days after the approval landed - the exact mis-scope the runbook's own Paul's-desk rule forbids. - Fixed two price contradictions still quoting the abandoned $25-50K band (assumptions-register E1, trigger-taxonomy "confirms our $25K band") plus market-analysis's "we do not need to discount" claim - all three fed sales collateral with numbers 3-10x the confirmed $2.5-10K offer. - Runbook history compressed (retro deduped to backlog, done S0 checklist collapsed to its spec file, done/archived card statuses corrected, artifact index brought current, playbook + send/monitor prompts indexed). - executive-summary now describes the real product (45-min context call + 48h offline AI-assisted audit), not live code-reading on the call. - cold-prospect-list carries an in-band ALL-ROWS-UNVERIFIED banner and the stale LIGHT-gate PASS is marked superseded; RUN.md trimmed to the one live prompt (P7); warm-intro kit promoted to PRIMARY-channel framing. Company layer: - Portfolio kill-criteria restored to full register wording (pause and re-open A + C, not just "the ICP bet") and stamped untestable - zero touches ever sent; the "why this bet" rationale now carries its counter-evidence (category name occupied, pricing-vs-thesis tension). - OS Rocks realigned arithmetic-first: KR2 needs 8-12 calls, the cold lane at full success yields ~2-3, so Rock 1 is now three lanes (warm PRIMARY - blocked only on Paul's ~10 names; LinkedIn drafts-only; cold top-up) with a falsifiable Sep-30 midpoint gate (>=3 calls or re-open A + C). - strategy.md: retracted "competitors are only just entering it" (20.09 found page 1 occupied a month ago; never propagated), cut the paid pilot, replaced the 18-day-stale current-state line with runbook pointers. Marketing (2510 + workflows): - GOAL-AT-A-GLANCE: replaced the 3-stream table that contradicted its own file twice (10/mo vs ~6/mo) with 20.09 SS7's five rows; deleted the dated status block that instructed publishing posts 20.09 explicitly cut; rankings row now carries the 6-12mo honesty; KR2 pointer to its owner. - Archived the three 2025 fossils (_ARCHIVED_ prefix: PROJECT-INDEX, TASK-TRACKER, READER-VALIDATION-REPORT-STATUS) and fixed the footer links that pointed the live overview at them. - Supersession banners added to 20.07/20.04/20.05 (20.08's banner was the only one that existed - now the pattern); 20.05's three-way state conflict (merged vs paused vs active) resolved to one sentence. - LinkedIn cadence canon: Stream 0 total is 3-4/wk SHARED across campaigns; both campaign plans claimed 5/wk each (10/wk combined). icp-validation stamped PAUSED (3/10 drafted, zero posted, zero data - revivable as the Rock-1 LinkedIn lane); course-promo stamped with real state; the post pipeline's campaign wiring made campaign-agnostic. Routers: - flow-router/BASE_HANDBOOK/AGENTS.md now route outbound/sales work to the runbook START HERE and company work to docs/business/ - previously no router in the repo sent a session to the entry point the OS designates. Dead /Users/pftg machine paths replaced with repo-root wording. - OKF indexes synced (outbound-sprint + scroll-gate listed; content-plan entry retitled to 20.09); dated log entry with the six durable lessons. Left on Paul's desk unchanged, now with decide-by framing: the ~10 warm names (the cheapest unblock on the board), Joy override, pricing stance, category name, vision-mission DRAFT flip. Gates: docs-only (zero content//themes/ files); course validators 8/8 green; grep sweeps clean (phantom board, stale prices, retracted claims, phantom gates, dead paths). 33 files, +198/-212. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LtDh9gdEPMZjaFKauRaRRs
Contributor
|
Important Review skippedToo many files! This PR contains 329 files, which is 229 over the limit of 100. To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. Usage-priced reviews support at most 300 files. ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (329)
You can disable this status message by setting the Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
…oss) Audit-verified before deletion: all 132 files in .claude/commands/ shared ONE md5 (3-line "Command (Stub)" placeholders) and injected 132 useless roster entries into every session; .claude/agents/templates/ (9 files, 54.9 KB) carried claude-flow hooks calling a binary that is not in package.json and not installed; .claude/agents/content/ duplicated kept agents behind fail-closed boilerplate citing dead paths; .claude/rules/ (5 files, 575 lines) were vendored Memoria docs mandating memory_* tools from an MCP server configured nowhere (no .mcp.json, no mcpServers block in any settings file). - DELETE .claude/commands/ (132 stubs) + docs/workflows/commands.md (the 19-line placeholder that existed only to receive them) - DELETE .claude/agents/templates/ + .claude/agents/content/ (nothing references either; 18 thin repo agents kept) - DELETE .claude/rules/ (Memoria vendor docs for an unconfigured server) - TRIM AGENTS.md 621 -> 74 lines: lines 77-621 were the rules files concatenated near-verbatim (2-6 differing lines per section); kept the unique head (project header, business layer, projects) + a tombstone telling future sessions where the memory docs went and when they may return (only with an actual .mcp.json) - settings.json: dropped dead CLAUDE_FLOW_* env keys and the permission allowlist entries pre-approving the uninstalled tool - DELETE .claude/hooks/pre-commit-screenshot-validation.md (.md in a hooks dir, not executable, referenced nowhere; the real hook is .githooks/pre-push) - .claude/skills/README.md: repointed from the host-only /Users/pftg path to the in-repo skill trees - FIXED a latent registration bug: six agents docs/workflows/agents.md lists as "Critical (keep)" had no YAML frontmatter and therefore never registered as invocable (core/coder, core/researcher, core/tester, qa-browser-tester, ui-problem-diagnosis-specialist, ux-browser-validator) - added minimal name/description/model frontmatter matching the registered siblings - Consolidated the kanban skill pair to one: kept kanban-md (CLI usage), removed kanban-based-development (its only consumer - the 2607 shared board - was never committed and no longer exists) Gates: config/docs-only; course validators 8/8 green (run at tranche end). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LtDh9gdEPMZjaFKauRaRRs
…hs, stale index Tranche 2 of the simplification plan (entry-point integrity): - docs/README.md rewritten lean: it declared a "/knowledge/ SUPREME AUTHORITY (inherited via symbolic link)" that resolves ONLY on Paul's host machine - a dangling symlink in every container/CI session - plus cross-project references (/projects/elital_search, elital_sync, snap_diff-capybara) that never existed in this repo, and a JD-area legend (70-79=Hugo, 80-89=visual testing) contradicting the actual areas. Every rule depending on those paths was unenforceable. The hub now points at what exists: CLAUDE.md -> docs/ -> .okf/, with a historical note so the lesson survives. - CLAUDE.md: TDD block repointed from the four /knowledge/ files to the in-repo doctrine (20-29-testing-qa + incidents), with /knowledge/ explicitly marked host-only; qmd search-target list drops knowledge/; the test-runner matrix stated 3x collapsed to the single header line; Quick Reference table pruned of duplicate rows and machine paths; the "Content plan (active)" pointer moved off superseded 20.07 to 20.09; claude-context search phrase made repo-root-relative. - The ~6 KB of 2605-course-specific policy (ICP-reader read-back, Write-for-Sam, Pilot-definition) moved verbatim to docs/projects/2605-.../60-69-policies/60.01-course-editing-policies.md with a one-line pointer left in CLAUDE.md - global sessions stop paying for course-only rules. - Fixed the broken _DEFERRED_external-validation-pilot-kit.md path (cited in CLAUDE.md, TASK-TRACKER, LOW-IMPACT-IDEAS-BANK; the real file is 40-49-review/40.18-external-validation-pilot-kit.md - the _DEFERRED_ filename never existed on disk). - docs/blog-post-index.md regenerated: it claimed 584 posts / updated 2026-04-11 against 607 actual - 23 posts invisible to the "never guess slugs" rule and its 7 callers. NEW bin/generate-blog-index (small Ruby, matches repo tooling) makes regeneration one command; first run surfaced and fixed a UTF-8/US-ASCII locale trap. Gates: docs+tooling only; course validators 8/8 green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LtDh9gdEPMZjaFKauRaRRs
Tranche 3. docs/ root held 28 loose files (10,798 lines) in violation of
the repo's own Johnny-Decimal filing rule; docs/README.md admitted they
were "legacy pending triage" - the triage was never done. Done now:
- 15 files MOVED to their JD homes with all inbound links repaired:
component-extraction-architecture -> 30-39; emergency-recovery-system
-> 50-59; the four test/visual-qa docs -> 20-29 (screenshot-testing);
seo-optimization-implementation-guide -> 90-99/seo-optimization;
hugo-team-best-practices -> 10-19; four agent-MCP docs -> 70-79;
two component docs -> docs/components/; refactoring-2 -> 2509 (which
owns FL burn-down).
- 10 files ARCHIVED with _ARCHIVED_ prefix + tombstone banner into their
owning area/project: plan/tasks/refactoring (2509 archives - all
phases complete or superseded), emergency-recovery-summary (derivative
of the doc it summarizes), three MCP-push reports (CLAUDE.md's own
report-file ban), local-semantic-search-setup (superseded by qmd),
test-quality-enforcement-summary (superseded by 60-69 doctrine),
jetthoughts-content-style-guide (voice-guide 90.11 is canonical).
- The October-2025 AI/LangChain SEO cohort - docs/seo/ (8 files),
docs/_runtime/ (10), docs/_research/ (2) - archived into
2510/70-79-archives/{seo-2025,_runtime-2025,_research-2025}/ with a
cohort tombstone. Superseded twice over (Apr-2026 ICP-E pivot, then
20.09 pipeline-first).
- CORRECTION to the audit while executing: docs/_research/ also held the
Russian-language business-idea-validation research that 2605's 10.08
analysis cites as a LIVE June-2026 source - moved it into
2605/10-19-research/ (not the archive) and repaired its four callers.
Lesson: date-cohort binning must check inbound links per-file.
- Fixed 6 links to docs/seo/80.xx files that NEVER existed (60.01,
60.02, 70.00) - dead since the day they were written.
Root survivors: README.md, SETUP.md, blog-post-index.md - each with
multiple live callers.
Gates: docs-only; course validators 8/8 green; per-file inbound-link
sweep returns zero references to any old path.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LtDh9gdEPMZjaFKauRaRRs
Tranche 4 - every project now states its truth in one screen: - 2605: TASK-TRACKER split 1,628 -> ~30 lines. The old head was a ~600-word single-paragraph "Last Updated" stale by 6 merged PRs, item numbering was physically out of order (14 sat 126 lines after 18), and ~72% of the file was closed-wave history. New tracker: dated status head, the Aug-14 metrics read as the next dated event, the four genuinely open items in execution order (16 landing migration RUNS NEXT, 18 SVG wave, 13 W4 post-Aug-14, 7 Wave-G batch 2), parked items with owners. Full history preserved in _ARCHIVED_TASK-TRACKER-2026-07.md (per the project's own convention) with item line-numbers in its banner. Wave plan 20.15 stamped CLOSED in-file (it was closed in a commit message 6 days ago but the file never learned); PROJECT-INDEX + GOAL-AT-A-GLANCE stale headers refreshed, including the index's "Active: external validation pilot" claim that contradicted the pilot-is-internal policy. - 2604: stamped CLOSED. Its two remaining P2 items re-homed: the 684px column-width question moved to 2509's Phase D backlog (cross-cutting CSS - 2509 owns it), reader-mode research already owned by 2605 item 14. findings-*.md stay (protected artifacts). - 2509: PROJECT-INDEX reconciled with its own tracker (it claimed "Phase 0" while the tracker said Phase C complete 2026-07-19 - 3 phases behind). The superseded-2026-07-12 archive tree (37 files, ~684 KB, ~4x the live project docs, describing the abandoned pre-redesign approach) pruned to a tombstone with a git-recovery pointer. The stray top-level projects/ dir (2 Oct-2025 log files that made the repo look like it had a second project root) archived into 2509's archives. Gates: docs-only; course validators 8/8 green; zero live references to any pruned path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LtDh9gdEPMZjaFKauRaRRs
Tranche 5 (JD hygiene) + the OKF log entry for the whole simplification: - SAFLA corpus archived: 76-safla-neural-xp-coordination/ (7 files, 6,382 lines, zero external inbound, bare-76 invalid JD area) moved under 70-79-ai-intelligence/_ARCHIVED_76-safla.../ + the 75.01-75.04 set prefixed _ARCHIVED_ (README links updated). It described claude-flow machinery that is not installed. - docs/30-39-architecture/ (7 CSS-era files, no README, zero inbound, colliding with the sanctioned 30-39-architecture-design/) folded into 2509's archives as 30-39-architecture-css-era/. - 80-89: Jekyll patterns archived (this is a Hugo site) + the ruby-expert validation report archived (report-file ban). - docs/visuals/ dissolved: the Excalidraw SVG guide archived into design-system/ with a supersession banner (O2 flat-vector + .okf/design/house-visual-spec.md replaced it in W3/#434); running-case-studies re-homed to 90-99. - design-system/course-landing-components-2026-08.md moved into 2605's 30-39-architecture-design/ (project material in a site-wide area); both inbound links repaired. - docs/adr/ double-0001 fixed (second file renamed 0002-) + README declaring adr/ the ONE site-wide ADR home, project ADRs stay in project trees. - READMEs added where their absence caused misfiling: 70-79-templates-boilerplates (documents the tolerated 70-79 range collision + internal 70.08 duplicate) and linkedin-posts/course-promo (mirrors the icp-validation entry point). - .okf/log.md: dated entry with the six durable lessons from tranches 1-5 (config-documents-only-installed-tools, supreme-authority-must- resolve, keep-lists-arent-existence-proofs, generated-not-asserted indexes, trackers-are-queues, per-file inbound checks on cohort archives). Deferred deliberately (documented in the OKF entry): the 60.xx duplicate renumbering + 60-69->20-29 testing-doc moves (M effort, inbound risk); .junie//GEMINI.md/QWEN.md mirrors (other tools' files). Gates: docs-only; course validators 8/8 green; inbound-link sweeps clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LtDh9gdEPMZjaFKauRaRRs
…rdcoded path The four agent-MCP docs moved to 70-79 in tranche 3 describe claude-flow machinery removed in tranche 1 - each now opens with a read-for-patterns- not-commands caveat pointing at docs/workflows/agents.md. blog-pipeline's claude-context example de-hardcoded to <repo root> like its siblings. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LtDh9gdEPMZjaFKauRaRRs
pftg
changed the title
pftg
marked this pull request as ready for review
August 8, 2026 18:42
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
One sprint, seven commits, two phases — approved plan executed in full.
Phase 1 (commit 1) — business/ops/sales/marketing consolidation
Single-owner truth for the company layer: phantom kanban board removed from the 2607 runbook entry point,
backlog.mdpromoted to sole card registry; phantom Paul-gates struck; three $25-50K price contradictions fixed against the confirmed $2.5-10K offer; OS Rocks realigned arithmetic-first (three demand lanes summing to KR2, Sep-30 falsifiable midpoint gate); portfolio kill-criteria restored to full register wording and stamped untestable — zero touches ever sent; 2510 GOAL-AT-A-GLANCE stopped instructing work the plan of record prohibits; LinkedIn cadence canon fixed (Stream 0 = 3-4/wk shared; both campaign plans stamped with real state); routers finally send sessions to the runbook START HERE.Phase 2 (commits 2-7) — AI-config purge + docs-estate simplification
Config (~115 KB removed, zero capability loss, all claims verified before deletion): 132 byte-identical stub slash-commands (one md5 across the whole dir — each a roster entry every session paid for) ·
.claude/agents/templates/+content/(claude-flow boilerplate whose hooks call an uninstalled binary) ·.claude/rules/(575 lines of vendored Memoria docs mandatingmemory_*tools from an MCP configured nowhere) · AGENTS.md 621 → 74 lines (88% was those rules concatenated) · dead env keys + permission allowlist entries · fixed a latent bug: six "Critical (keep)" agents had no YAML frontmatter and never actually registered.Entry points:
docs/README.mddeclared a/knowledge/"SUPREME AUTHORITY" that is a dangling symlink outside Paul's Mac, plus three cross-project repos that never existed — rewritten lean with the lesson recorded. CLAUDE.md: TDD block repointed to in-repo doctrine, test-runner matrix de-triplicated, ~6 KB of 2605-only policy moved into the project, broken_DEFERRED_path fixed, stale content-plan pointer moved to 20.09.blog-post-index.mdregenerated (claimed 584 posts vs 607 actual) with a newbin/generate-blog-indexso it can't silently drift again.Docs root 28 → 3 files: 15 moved to their Johnny-Decimal homes (all inbound links repaired), 10 archived with tombstones, the Oct-2025 AI/LangChain SEO cohort (
docs/seo/,_runtime/,_research/) archived into 2510 — with one audit correction caught in execution: a Russian-language research doc in that cohort is a live 2605 source and went into 2605's research tree instead. Six links todocs/seo/80.xxfiles that never existed, fixed.Projects: 2605 tracker split 1,628 → ~30 lines (live queue only: item 16 landing migration runs next, 18, 13, 7, Aug-14 metrics read; history in
_ARCHIVED_TASK-TRACKER-2026-07.md); wave plan 20.15 stamped CLOSED in-file; 2604 stamped closed with its two items re-homed; 2509's index reconciled with its own tracker (was 3 phases behind) and its 37-file superseded tree pruned to a git-recovery tombstone; the stray top-levelprojects/dir dissolved.JD hygiene: SAFLA corpus archived (6,382 lines, zero external inbound); CSS-era
30-39-architecture/collision folded into 2509 archives; Jekyll patterns + a validation report archived in 80-89;docs/visuals/dissolved (Excalidraw guide superseded by the O2 spec); ADR double-0001fixed +docs/adr/declared the one site-wide ADR home; missing READMEs seeded.Deferred deliberately (documented in
.okf/log.md): the 60.xx duplicate renumbering and 60-69→20-29 testing-doc moves;.junie//GEMINI.md/QWEN.md (other tools' mirrors).Gates
Docs/config only — zero files under
content/orthemes/. Course validators 8/8 green on every commit. Verification sweeps clean:Command (Stub)zero; livememory_*mandates zero; phantom paths (elital_,docs/seo/80.xx,_DEFERRED_external-validation) zero; every CLAUDE.md/README/AGENTS.md path reference resolves (the one intentional exception: the report-file ban's example filename, which correctly names a file that must not exist). OKF log carries the six durable lessons.