docs: compound — durable lessons from docs site revival#88
Merged
Conversation
Three new durable lessons extracted from session-05809d (PR #87): 1. post-deletion-promise-debt-anti-pattern (best-practices) — deleting an in-tree asset with the explicit intent to recreate elsewhere creates load-bearing orphans. The recreation almost never happens without a draft follow-up PR; the deleted artifact's last build keeps serving (Pages doesn't auto-tear-down) and silently rots. Surfaced when the May-1 docs snapshot served stale prose for 6 days after PR #53 deleted packages/docs/ with the promise to spin up theagenticguy/opencodehub-docs that never happened. 2. exclude-heavy-build-from-pnpm-recursive (architecture-patterns) — packages whose build pulls in heavy tooling (Playwright, browser binaries, model weights) should be filtered out of `pnpm -r build/test` in workflows that don't own that build. Surfaced when restoring @opencodehub/docs broke ci.yml typecheck + och-self-scan + release.yml build because none of them install Chromium. 3. banned-strings-policy-evolves-with-product (conventions) — a banned-string allowlist that was correct during decision-making becomes wrong once the decision ships. LadybugDB was banned during graph-engine evaluation; after M3+M7 made it the default backend, the bare product name became critical prose surface. Re-audit the ban list at every release. INDEX.md updated with the three new entries.
Closed
theagenticguy
added a commit
that referenced
this pull request
May 10, 2026
## Summary Compound phase from session-05809d (PR #87). Three new durable lessons from the Starlight docs site revival. | File | Category | Surfaced by | |---|---|---| | `post-deletion-promise-debt-anti-pattern.md` | best-practices | PR #53's promise to spin up `theagenticguy/opencodehub-docs` was never kept; the orphaned May-1 build served stale docs for 6 days | | `exclude-heavy-build-from-pnpm-recursive.md` | architecture-patterns | Restoring `@opencodehub/docs` broke `ci.yml` typecheck, `och-self-scan`, and `release.yml` build — none install Chromium for Playwright/rehype-mermaid | | `banned-strings-policy-evolves-with-product.md` | conventions | LadybugDB was banned during graph-engine evaluation; after M3+M7 made it the default, the bare product name became critical prose surface | ## Test plan - [ ] CI green - [ ] Future ERPAVal sessions surface these three on `INDEX.md`
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
1 participant
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.
Summary
Compound phase from session-05809d (PR #87). Three new durable lessons from the Starlight docs site revival.
post-deletion-promise-debt-anti-pattern.mdtheagenticguy/opencodehub-docswas never kept; the orphaned May-1 build served stale docs for 6 daysexclude-heavy-build-from-pnpm-recursive.md@opencodehub/docsbrokeci.ymltypecheck,och-self-scan, andrelease.ymlbuild — none install Chromium for Playwright/rehype-mermaidbanned-strings-policy-evolves-with-product.mdTest plan
INDEX.md