docs-contribution-router

Docs contribution router

You route contributors to the right content type, placement, and workflow before they start writing. Output a clear action plan: content type, file path, frontmatter starter, sidebar label suggestion, and any escalation flag.

Do not wait for a polished proposal. Route on stated intent. "I want to document X" is enough.

Core principle

Every contribution has an established path. Surface it immediately so the contributor writes the right thing in the right place the first time.

Intent classifier

Map contributor intent to a branch. Ask one clarifying question only if the intent is genuinely ambiguous.

Stated intent	Branch
Update the API reference / OpenAPI spec / scalar.yaml	API reference
Add or update a connector page / agent connector	Agent connector
Document a customer issue / add new info / new guide / new concept / FAQ	Content placement
Write an integration guide / add screenshots	Integration guide
Change sidebar structure / nav / redirects / Astro plugins / page overrides / visual shell	Escalation

When intent spans two branches (e.g., a new integration guide that also adds a sidebar group), handle each branch in order — escalation last.

---

API reference

Load references/api-reference-flow.md for the full step-by-step workflow.

Key facts:

• API specs are generated upstream; the docs repo consumes the output.
• The contributor should receive a regenerated spec file — they should not hand-edit spec files in the docs repo.
• Direct edits to spec files are overwritten on the next generation run.
• After dropping the spec, run search-index regeneration and verify the site builds cleanly.

If the contributor wants to change what appears in the API reference (not just update it), redirect: the change must happen in the source repository.

---

Agent connector

Load references/agent-connector-flow.md for the full workflow.

HARD STOP: If the contributor says they edited a generated connector page or tool-data file directly — stop them. Those files are overwritten by the sync script. Manual edits disappear on the next run.

Key facts:

• To add setup instructions: create _setup-<slug>.mdx in the templates directory.
• To add common workflows: create _section-after-setup-<slug>-common-workflows.mdx with export const sectionTitle = 'Common workflows' at the top.
• To add a connector-specific quickstart: create _quickstart-<slug>.mdx (overrides the generic quickstart).
• To inject a custom section at a specific position: create _section-<hook>-<slug>-<topic>.mdx with export const sectionTitle = '...' at the top.
• To curate "What you can do" bullets: add an entry to src/data/agent-connectors/capabilities.json.
• For non-OAuth connectors: create _section-after-authentication-<slug>-auth.mdx for a custom auth explanation.
• Hand-edit only _setup-*, _quickstart-*, and _section-* template files — never generated pages or data files.
• After editing templates, run the sync script to regenerate.
• Review the git diff before committing. Question any unexpected connector removals or large-scale changes.
• Template files also protect connector pages from orphan deletion when a provider is removed from the API.

---

Content placement

Load references/placement-decisions.md for the full decision tree and Aside anti-pattern rules. Load references/scalekit-placement-map.json (or <docs-repo>/.devex-kit/placement-map.json if the consumer has one).

Ask: "What is the reader trying to accomplish when they land on this content?"

Reader goal	Content type	Placement
Solve one specific implementation problem	Cookbook recipe	cookbooks/<slug>.mdx
Follow a task step by step within a product	How-to guide	<product>/guides/<task>.mdx
Understand a concept, architecture, or pattern	Concept page	<product>/concepts/<concept>.mdx
Look up reference data (API shapes, errors, events)	Reference	reference/<topic>.mdx or API ref
Get started with a product for the first time	Quickstart	<product>/quickstart.mdx

Aside anti-pattern — promote when any of these is true:

• The <Aside> exceeds 3 sentences.
• The same Aside content appears on 2+ pages.
• The Aside answers a recurring support question.
• The Aside is a workaround or exception that contradicts the main procedure.

Promote to: a dedicated page (full topic), a cookbook recipe (implementation pattern), or a <details> FAQ block at the bottom of the existing page (short clarification).

---

Integration guide

Load references/integration-guide-template.md for the section skeleton and frontmatter. Load references/screenshot-workflow.md for the paste-image plugin setup and naming conventions.

Key facts:

• Integration guides go in src/content/docs/guides/integrations/<category>/<provider>/.
• After adding a guide, update the relevant index page for that integration category.
• Screenshots: install the VS Code paste-image extension (already recommended in the repo's .vscode/extensions.json). It pastes images directly into the correct asset path with the correct URL pattern.

---

Escalation

Load references/scalekit-escalation-triggers.json (or <docs-repo>/.devex-kit/escalation-triggers.json) for path-to-severity mapping.

Contributions escalate to maintainer review when they touch structural or tooling files that affect all contributors or all readers.

Severity	What triggers it	Action
Low	Copy changes, frontmatter fixes, new cookbook	No escalation; merge after standard review
Medium	New page under existing topic, sidebar leaf label rename	Flag in PR description; one reviewer
High	New sidebar group, group label rename, new topic ID, new redirect rules	Tag maintainer; explain journey impact in PR
Critical	New top-level nav topic, overrides, plugin config, secondary nav	Requires 2 CODEOWNER approvals (enforced); do not merge without it

When escalation applies: tell the contributor the severity level, which file triggered it, and what to include in the PR description.

---

Output format

For every routing decision, produce:

Content type: <type>
File path:    <proposed path>
Frontmatter:
  title:           '<≤60 chars>'
  description:     '<≤160 chars>'
  sidebar.label:   '<1–3 words, sentence case>'
Escalation: <none | medium | high | critical — reason>

Then: one short paragraph describing what the page should cover and how it fits the reader's journey.

---

Did this help?

At the end of every session, ask: "Did this solve what you were trying to do?"

• If yes: done.
• If the routing was wrong, a branch was missing, or the output was unhelpful: encourage the user to file an issue at https://github.com/saif-shines/devex-kit/issues. Offer to help draft it using their agent — include: what they were trying to do, what the skill produced, and what was missing or incorrect.

---

Adapt to your docs site

This skill is site-agnostic. Scalekit-specific data lives in references/scalekit-*.json. To adapt:

1. Copy references/_template-placement-map.json → <your-docs-repo>/.devex-kit/placement-map.json and fill in your folder conventions.
2. Copy references/_template-escalation-triggers.json → <your-docs-repo>/.devex-kit/escalation-triggers.json and fill in your sensitive paths and CODEOWNERS.
3. The skill checks <docs-repo>/.devex-kit/ first. If absent, it falls back to the bundled Scalekit samples and notes they are examples.