docs: add 9 blog posts, 4 tutorials, and tutorials section - #260
docs: add 9 blog posts, 4 tutorials, and tutorials section#260jflowers wants to merge 7 commits into
Conversation
yvonnedevlinrh
left a comment
There was a problem hiding this comment.
Verdict: REQUEST CHANGES (0 CRITICAL, 3 HIGH, 2 MEDIUM, 1 LOW)
What it does: Adds 9 blog posts + 4 tutorials + a new Tutorials nav section; claims to close 13 issues. Build passes (206 pages, npm run build exit 0). Content quality, security, and structure are strong.
Blocking Issues
| # | Severity | Finding |
|---|---|---|
| 1 | HIGH | The 4 new tutorials lack slug: frontmatter, so Hugo derives their URLs from titles. This breaks 7 internal links: 3 blog→tutorial links and 4 links in _index.md. |
| 2 | HIGH | onboard-customization title contains a literal /, producing a mangled URL /docs/tutorials/getting-started-with-/ (empty trailing segment). |
| 3 | HIGH | Zero-Waste Mandate violation — dead internal links shipping to production. Same root cause as #1. |
| 4 | MEDIUM | Tutorial count discrepancy: PR title says "5 tutorials", body and implementation say "4" (pinkman tutorial was removed). |
| 5 | MEDIUM | specs/tutorials.md still lists the removed Pinkman OSS Scout tutorial (#45) and states "5 tutorials / 15 pages" (actual: 4 tutorials / 14 pages). tasks.md correctly strikes the pinkman task, so spec and tasks disagree. |
| 6 | LOW | gaze crap baseline command in gaze-baseline-comparison.md may differ from the command specified in issue #151 — verify for copy-paste accuracy. |
Dead Link Detail
Tutorials render at title-derived URLs, but links point to filename-based slugs:
content/blog/gaze-baseline-comparison.md:143→/docs/tutorials/gaze-crap-baseline-ci/(actual:/docs/tutorials/setting-up-crap-baseline-comparison-in-ci/)content/blog/dewey-knowledge-stores.md:169→/docs/tutorials/dewey-knowledge-stores/(actual:/docs/tutorials/setting-up-dewey-knowledge-stores/)content/blog/pluggable-llm-providers.md:151→/docs/tutorials/dewey-provider-configuration/(actual:/docs/tutorials/configuring-dewey-embedding-and-synthesis-providers/)content/docs/tutorials/_index.md:14-17→ all 4 filename-based slugs, all dead
Not Blocking
- WARN-level "Description too short" messages on auto-generated
/tags/*taxonomy pages. Unrelated to this PR; does not affect the verdict.
Root Cause & Fix
A single mechanical omission — tutorials have no slug: frontmatter. The spec's own Tutorial Frontmatter requirement (specs/tutorials.md) also omits slug, which propagated into implementation.
- Add
slug:matching each filename to the 4 tutorial frontmatter blocks (dewey-knowledge-stores,dewey-provider-configuration,gaze-crap-baseline-ci,onboard-customization), thennpm run buildand verify the links resolve inpublic/. - Correct the PR title to "4 tutorials" and sync
specs/tutorials.md(remove pinkman #45; change "5 tutorials / 15 pages" → "4 tutorials / 14 pages"). - (LOW) Verify the
gaze crapbaseline command against the gaze repo.
Content quality, security (SHA-pinned Actions, no secrets), and build health are otherwise strong.
…racter Add slug: frontmatter to all 4 tutorials so Hugo generates URLs matching the filename stems used in internal links. Fix the onboard-customization title by removing the literal "/" that caused Hugo to produce a mangled URL path. Addresses PR #260 review feedback from @yvonnedevlinrh. Signed-off-by: jflowers <jflowers@users.noreply.github.com> Assisted-by: claude-opus
Remove the Pinkman OSS Scout Tutorial requirement that was already struck from tasks.md. Update build validation scenario from "5 tutorials / 15 pages" to "4 tutorials / 14 pages" to match the actual implementation. Addresses PR #260 review feedback from @yvonnedevlinrh. Signed-off-by: jflowers <jflowers@users.noreply.github.com> Assisted-by: claude-opus
|
Thanks for the thorough review, @yvonnedevlinrh! All findings addressed: 1. Missing 2. Invalid 3. Zero-Waste Mandate — dead internal links (HIGH) 4. PR title "5 tutorials" → "4 tutorials" (MEDIUM) 5. Spec still references removed Pinkman tutorial (MEDIUM) 6. |
Blog posts covering: - CI failure classification (#64) - AGENTS.md quality auditing (#65) - Dewey knowledge stores (#69) - Dewey slash command UX (#72) - Pluggable LLM providers (#116) - Gaze baseline comparison (#150) - Council review action (#191) - Prompt hardening (#198) - Multi-platform support (#51) Tutorials covering: - Dewey knowledge stores (#70) - Dewey provider configuration (#114) - Gaze CRAP baseline CI (#151) - Pinkman OSS Scout (#45) - Onboard customization (#46) Adds Tutorials section to navigation menu.
…s-refs, align schemas - Remove pinkman-oss-scout.md tutorial per user direction - Fix dead cross-references in dewey-knowledge-stores blog (correct slugs) - Fix dead link in dewey-knowledge-stores tutorial (/docs/projects/dewey/) - SHA-pin GitHub Actions in gaze-baseline-comparison blog - Add missing code block language IDs (FT-001) across 5 files - Fix Constitution Principle III name (Observable Quality, not Actionable Output) - Align pluggable-llm-providers blog with tutorial (vertexai, claude model, config path) - Add blog↔tutorial cross-links in both directions - Align knowledge stores YAML schema between blog and tutorial - Standardize gaze CLI flag to --format=json - Fix MCP tool call syntax labels in dewey-knowledge-stores tutorial - Add explicit tutorial list to _index.md - Add Further Reading sections to all tutorials - Update ci-failure-classification CTA with specific link
Assisted-by: claude-opus Generated with AI assistance (claude-opus)
…racter Add slug: frontmatter to all 4 tutorials so Hugo generates URLs matching the filename stems used in internal links. Fix the onboard-customization title by removing the literal "/" that caused Hugo to produce a mangled URL path. Addresses PR #260 review feedback from @yvonnedevlinrh. Signed-off-by: jflowers <jflowers@users.noreply.github.com> Assisted-by: claude-opus
Remove the Pinkman OSS Scout Tutorial requirement that was already struck from tasks.md. Update build validation scenario from "5 tutorials / 15 pages" to "4 tutorials / 14 pages" to match the actual implementation. Addresses PR #260 review feedback from @yvonnedevlinrh. Signed-off-by: jflowers <jflowers@users.noreply.github.com> Assisted-by: claude-opus
457857f to
37e79bd
Compare
Summary
Adds a batch of 9 blog posts and 4 tutorials to the Unbound Force website, plus a new Tutorials documentation section. This closes 13 tracked GitHub issues in a single coordinated effort.
Blog posts cover recent releases and capabilities:
/review-prsignal vs noise)/dewey-storezero-code UX)uf init --platform)Tutorials provide step-by-step guides:
/onboardCloses #46, #51, #64, #65, #69, #70, #72, #114, #116, #150, #151, #191, #198
How to Test
npm run build— should produce 206 pages with no errorsnpm run devand verify:/docs/tutorials/How to Demo
Key Files Changed
Config:
menus.en.toml— added tutorials nav entry at weight 37Blog (9 new):
agents-md-quality.md,ci-failure-classification.md,council-review-action.md,dewey-knowledge-stores.md,dewey-slash-command-ux.md,gaze-baseline-comparison.md,multi-platform-support.md,pluggable-llm-providers.md,prompt-hardening.mdTutorials (5 new):
_index.md,dewey-knowledge-stores.md,dewey-provider-configuration.md,gaze-crap-baseline-ci.md,onboard-customization.mdOpenSpec artifacts (6 new): proposal, design, specs, tasks for
blog-tutorials-batchDewey learnings (2 new): retrospective learnings from the implementation session
This PR was generated by /uf.finale (AI-assisted).