Skip to content

Commit d2ff0bb

Browse files
cdeustclaude
andcommitted
feat(wiki): add installation / troubleshooting / contributing how-to scopes
The 15-scope catalogue covered explanation (architecture, services, data-flow), reference (api, commands, tools, mcp, ci-cd), and one tutorial (onboarding) — but the Diátaxis how-to quadrant was empty. Users with a concrete goal (install on a fresh box, fix a known error, land their first PR) had no canonical landing page. Three new universal scopes: * ``installation`` — install + configuration walk-through, OS by OS, every env var named with its default, post-install verification commands. Anchor filenames: install / installation / configuration. Suggested kind: how-to. * ``troubleshooting`` — symptom → diagnosis → fix table for every known issue and common error. Sourced from runbook incidents + ADR consequences + lessons. Anchor filenames: troubleshooting / known-issues / faq / common-errors. Suggested kind: how-to. * ``contributing`` — fork/branch policy, test commands, lint rules, commit convention, PR review expectations. Distinct from onboarding (which is day-one setup); this is the edit-to-merge path. Anchor filenames: contributing / CONTRIBUTING / contribute / development. Suggested kind: how-to. Total canonical scopes: 15 → 18. cortex coverage drops from 15/15 to 15/18 until the autonomous worker authors the new anchors on the next cycle; every other project's coverage gap grows by 3 likewise and the worker drains them in priority order. 121 wiki tests + ruff format + ruff check all green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 04b7b08 commit d2ff0bb

1 file changed

Lines changed: 68 additions & 0 deletions

File tree

mcp_server/core/wiki_coverage.py

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -340,6 +340,74 @@ class Scope:
340340
directories=("guides", "tutorial"),
341341
suggested_kind="tutorial",
342342
),
343+
# ── Task-oriented how-to guides (Diátaxis: how-to quadrant) ────────
344+
#
345+
# Onboarding above and code-walkthrough cover the learning + reading
346+
# axes; what's missing is the *task-oriented* how-to layer — the
347+
# guides a user hits when they have a concrete goal already
348+
# (install, fix a known error, contribute). Three universal
349+
# categories cover the bulk of project-level user demand:
350+
Scope(
351+
name="installation",
352+
title="Installation & configuration",
353+
description=(
354+
"Step-by-step install + configuration walk-through, OS by OS, "
355+
"with every environment variable named and its default. Beyond "
356+
"onboarding (which is the day-one path) this is the reference "
357+
"for every configuration knob, every install variant (CLI, "
358+
"Docker, source clone, plugin marketplace), and the post-"
359+
"install verification commands. Include screenshots / sample "
360+
"configs where useful."
361+
),
362+
anchor_filenames=(
363+
"installation.md",
364+
"install.md",
365+
"configuration.md",
366+
"configure.md",
367+
),
368+
directories=("guides", "how-to"),
369+
suggested_kind="how-to",
370+
),
371+
Scope(
372+
name="troubleshooting",
373+
title="Troubleshooting & known issues",
374+
description=(
375+
"Symptom → diagnosis → fix table for every known issue, "
376+
"common error message, and pitfall. Each entry: the exact "
377+
"log line or symptom, root cause, recovery steps, prevention. "
378+
"Sourced from runbook incidents + ADR consequences + lessons "
379+
"captured in memory. The page a user opens when something "
380+
"breaks at 3am."
381+
),
382+
anchor_filenames=(
383+
"troubleshooting.md",
384+
"known-issues.md",
385+
"faq.md",
386+
"common-errors.md",
387+
),
388+
directories=("guides", "how-to", "runbook"),
389+
suggested_kind="how-to",
390+
),
391+
Scope(
392+
name="contributing",
393+
title="Contributing guide",
394+
description=(
395+
"How to land a change in this project: fork / branch policy, "
396+
"test commands, lint rules, commit-message convention, PR "
397+
"template, code-review expectations, who reviews what, how "
398+
"long things typically take. Distinct from onboarding "
399+
"(reader is already set up); this is the path from edit to "
400+
"merge."
401+
),
402+
anchor_filenames=(
403+
"contributing.md",
404+
"CONTRIBUTING.md",
405+
"contribute.md",
406+
"development.md",
407+
),
408+
directories=("guides", "how-to"),
409+
suggested_kind="how-to",
410+
),
343411
)
344412

345413

0 commit comments

Comments
 (0)