Write answer-first troubleshooting documentation

Start a troubleshooting article with the confirmed fix and the condition that makes it appropriate. Then help the reader recognize the symptom, check applicability and prerequisites, act safely, and verify the result. Put supporting rationale after the steps, not between the reader and the answer.

Use the troubleshooting article template for one diagnosed symptom at a time. Update an existing article instead of creating a duplicate. The template ships inside the documentation skill, alongside a bundled copy of this contract in that skill's references/troubleshooting-pages.md, so agents can apply it without access to this site. This page remains the published authoring contract; update both when the contract changes.

Page shape

1. Searchable title and concise answer: name the error or symptom using the words readers search for. Open with one or two sentences naming the fix and its conditions, not an unexplained command.
2. Symptom: quote the exact stable error wording in a language-tagged code block. Say where and when it appears and include any check needed to distinguish similar failures. Redact credentials, customer data, and environment-specific sensitive values without removing the searchable error.
3. Applicability, prerequisites, and safety: identify the affected versions and environments, when the fix does not apply, required tools and permissions, and the target execution context. Put necessary warnings, backup requirements, and recovery guidance before commands that change state.
4. Fix: give the smallest confirmed fix in numbered, observable steps. State conditions before alternative commands, label placeholders, and keep action-specific warnings beside their steps.
5. Verify: repeat the failing operation or test the intended result. Show expected output or state and a safe next check if the symptom remains.
6. Cause and related guidance: explain why the fix works, then link deeper reference material and the source report. Keep diagnostic facts needed to choose the fix earlier.

Use enough detail to complete the task safely. There is no line-count target. Keep paragraphs, list items, and blockquotes on single logical source lines and let the editor soft-wrap them.

This is a troubleshooting task template, not a universal layout. Keep tutorial learning sequences and explanation scaffolding.

One maintained home per topic

Capability hubs under Build help readers choose a task. Open with useful choices and link the owning guides, reference, and fixes rather than copying their instructions. Reference pages own exact options, constraints, and technical mechanics; task guides own the steps to reach an outcome. About tells Forge's story and direction, while technical architecture stays under Reference.

Before repeating a fact, ask where it will be updated when behavior changes. A short summary or worked example is useful context, but it should link the authoritative explanation rather than introduce another full matrix or procedure. Generated package reference comes from source READMEs, and the CLI command inventory comes from the guarded CLI manifest. Edit those producers, never their generated documentation copies.

Troubleshooting identifiers

Single-symptom articles live at troubleshoot/<readable-slug>.md and carry id: SAIFTRBL0001-style frontmatter. Assign IDs from one global sequence, with at least four digits, no domain ranges, and no reuse or renumbering. Before allocating the next number, inspect the current catalog and history of retired articles; removing an article does not make its number available again. Recheck before merge if another article merged first. Keep an existing article's ID when correcting its title or fix.

The catalog is generated from article metadata; the docs build rejects duplicate or malformed identifiers and any page under troubleshoot/ with no ID. Every page there is a single-symptom article except the landing page and the generated catalog, which do not receive IDs or the troubleshooting article tag. Do not add diagnostic hubs or general guidance pages under troubleshoot/; put that guidance in the owning task guide or reference page. These identifiers describe articles, not compiler warnings; existing SAIFENV001 and other named diagnostic codes retain their IDs and URLs.

Articles keep readable canonical routes, and former routes redirect through moved_from. Each article's ID also resolves as troubleshoot/<ID>/ through a redirect that docs/hooks/redirect_map.py generates on both sites, so share or link the ID URL when you want a link that survives slug changes. Retrieval tools do not follow that redirect; see retrieval limits. Forge tooling does not emit troubleshooting URLs: these articles cover errors that providers, Azure, MSBuild, and pipeline templates raise, and an error that Forge code links to is a diagnostic with a SAIF* code under diagnostics.

Metadata contract

Apply this contract to the explicit pilot set and newly added published authored pages. Do not backfill unchanged legacy pages or hand-edit generated output; change its producer instead. Templates do not count as published articles.

Field	Authored shape	Requirement
title	Non-empty YAML string	Required; identify the task or symptom clearly.
description	Non-empty YAML string	Required; summarize the problem and outcome. Also write a useful opening answer in the body.
tags	YAML list of non-empty strings	Optional except for troubleshooting articles, which require troubleshooting and at least one existing component tag.
moved_from	Optional YAML list of docs-relative Markdown paths	For a moved or merged published page, record each former path.

Applicability is not a metadata field. Tags already say which component an article covers, and the affected versions, environments, and conditions belong in the article's own Applies to section, where a reader browsing or reading downloaded Markdown can check them. Do not add a parallel applies_to property that restates the title or the opening answer.

---
title: Exact error or symptom
description: A concise statement of the problem and its confirmed fix.
tags:
  - troubleshooting
  - build
moved_from:
  - guides/troubleshooting/old-slug.md
  - foundry/old-example.md
---

Use the existing troubleshooting component vocabulary. If no component tag fits, propose an addition there in the same PR instead of introducing a second taxonomy. Keep tag terms literal and unambiguous, without duplicates, surrounding whitespace, commas, or line breaks. Authors write YAML lists, not a comma-separated scalar or a separate keywords property.

The same authored title, description, and tag terms supply page metadata. Tags retain their meaning when the existing search transport joins them with commas. This contract does not introduce tag-filter behavior or map applicability into a search filter.

Do not add a required reviewed date, capability, stable_id, or deprecated_after. For a moved or merged page, preserve its former docs-relative Markdown paths in a moved_from list, and preserve important heading anchors. python -m mkdocs build --strict rejects malformed, duplicate, unpublished, or still-live entries, and generates an HTML redirect from each former path to the page (docs/hooks/redirect_map.py), so do not hand-write redirect configuration. Retrieval tools do not resolve former paths; see retrieval limits for why a caller passing a pre-move location gets not_found. Do not add an article's id to moved_from; the build already generates its ID redirect.

Review and validation

• Confirm the fix from source or a reproduced diagnosis, and check vendor-specific instructions against current official documentation.
• Check that a reader can identify the right scenario, prerequisites, and safety constraints before running the fix.
• Keep the existing URL and important heading fragments when editing a surviving page. Retain the heading or an explicit anchor if the wording changes.
• Check relative links, language-tagged commands, placeholders, expected output, and source attribution.
• Check title, description, and tags against the shapes above; a passing build is not evidence of human task success on its own.

Build both checked-in documentation configurations to validate the site separately:

python -m mkdocs build --strict
python -m mkdocs build --strict --config-file mkdocs-shared.yml

After a strict build, run python tools/docs-links/check_docs_links.py --site-dir staticsite to check the built site the same way CI does: repository-relative docs/... references, published site URLs, and real HTML fragment and heading IDs. Add genuinely intentional exceptions, such as example paths that only look external, to tools/docs-links/allowlist.txt rather than changing the checker.

If the build reports missing Python dependencies, install the checked-in requirements with pip install -r docs/requirements.txt and retry. Use observed reader task attempts to evaluate usefulness separately from structural validation.