Docs Answerability Pass

---
name: docs-answerability-pass
description: Monthly review of 20 docs pages for direct answers, crawlability and AI citations, with ranked fixes and drafted answer-first intros and FAQs.
---

# Docs Answerability Pass

Review 20 documentation pages to see whether they answer buyer questions directly and earn citations from AI engines. Documentation and marketing teams get a ranked fix list, replacement intros and FAQ drafts. Part of the [Answer Engine Optimization (AEO) skillset](https://type.com/library/skills/answer-engine-optimization).

## When it runs

- Recommended schedule: the first Tuesday of each month at 10am in `timezone`.
- Post one report to `report_channel`, capped at 12 lines, and save detailed drafts in the monthly docs answerability doc. This skill sends no DMs.
- Schedule with a true first-Tuesday rule. If using cron, require Tuesday AND day-of-month 1–7; standard cron commonly ORs these fields.

## Inputs

| Input | What it is | Example |
| --- | --- | --- |
| `brand_name`, `brand_exclusions` | Exact brand spelling and look-alike names that must not count | Example, Example Writer |
| `docs_url`, `sitemap_urls` | Documentation domain and sitemap or sitemap index URLs | https://docs.example.com, https://docs.example.com/sitemap-index.xml |
| `tracker_monitors`, `tracker_engines` | Buyer-problems panel and engines to inspect | Buyer panel; ChatGPT search, Google AI Mode, Claude, Codex |
| `feature_topics` | Feature topics present in the panel's buyer-problem questions | Integrations, approvals, security |
| `master_doc`, `docs_answerability_doc` | AEO master doc and monthly docs answerability doc location | Workspace doc links |
| `report_channel`, `owner`, `timezone` | Report channel, action owner and scheduling timezone | #aeo, @owner, America/Los_Angeles |

## Before you start

- Connect Promptwatch in type.com as a Custom API connection using your Promptwatch project API key. Another tracker works if it exposes equivalent citation and panel-answer data.
- You need read-only site and tracker access, a report-channel connection, and scoped writes to the named shared docs.
- Reuse the AEO master doc and a docs answerability doc for the month. If absent on first run, create the missing docs and sections below and tell the owner where they are.
- The master doc stores reviewed URLs under `## Docs answerability` with a `### Reviewed` list. It also holds the `## Action tracker`.

## Steps

### 1. Choose 20 pages

Fetch the docs sitemap, following its sitemap indexes. Some docs platforms use /sitemap-index.xml instead of /sitemap.xml; try both if the configured sitemap is missing.

Read `citations/grouped` with a 90-day date range, filter to `docs_url`, and paginate through all citation pages. Choose:

- The 8 most-cited docs URLs over the last 90 days.
- 6 pages for features present in the panel's buyer-problem questions that have never been cited.
- 6 pages not reviewed in a previous pass, using the master doc's Reviewed list.

Use 20 distinct pages when available. If fewer eligible pages exist, report the actual sample size and the missing category rather than inventing pages or citation history.

### 2. Inspect each page in order

For every sampled page:

1. Fetch as GPTBot and Googlebot. Record status, noindex, title, H1, JSON-LD (TechArticle/FAQPage/HowTo), visible text length and last updated date.
2. Write the one question a user or buyer would type to find the page, in their words rather than yours.
3. Score the first 150 words of visible text: does it answer that question directly (yes / partly / no)? Does it name the product exactly as `brand_name`? Does it state prerequisites and the outcome? Are there steps or a table an engine can quote? Exclude `brand_exclusions` from brand mentions.
4. Check whether any engine cited this URL in 90 days and for which questions. If not, inspect panel answers mentioning the same feature: is a competitor's doc cited for the equivalent question, and what does it do differently? Use the tracker's `responses` for the configured monitors and engines, paginating through results.
5. Draft a replacement answer-first intro: 2–4 sentences, factual, mentioning `brand_name` once. Where appropriate, draft 3 FAQ pairs for FAQPage markup.

### 3. Save the monthly drafts

Create or update the named monthly docs answerability doc, titled "<brand_name> docs answerability — <Month YYYY>". Include the summary table:

URL | question | answers directly? | cited 90d? | schema | fix priority

Then include one section per page with the drafted intro and FAQs. Prioritize pages tied to panel questions and never cited.

### 4. Report and track fixes

Post the report below to `report_channel`. Confirm the post succeeded before finishing.

Add the top 5 fixes to the AEO master doc's `## Action tracker`. Create the section if missing with columns # | Action | Source | Owner | Status | Added | Done. Set Source = "docs pass", Owner = "unassigned", Status = "open". Append the reviewed URLs to the Docs answerability section's Reviewed list. Scope edits to these sections only.

## What it posts

Maximum 12 lines, with Do next before the headline and evidence:

```text
Do next
1. Eng/docs owner: replace the intro on <URL> with the drafted answer to "<question>" — never cited; <competitor> doc is — draft → <link>
2. Eng: add FAQPage schema (3 pairs drafted) to <URL> — draft → <link>
3. <owner>: <verb> <exact URL> · <single change> — draft → <link>
Docs answerability — <Month> · <n> pages · <n> answer directly · <n> cited by engines
Why
• <URL> · <question> · answers directly? · cited 90d?
Details → <monthly docs answerability doc link>
```

Do next has at most 3 actions. Why has at most 5 one-line bullets for the next 5 worst pages.

## Output rules

- Lead with the action. Every Do next item is one line: owner + verb + exact URL + single change + link to the drafted text.
- Numbers, not adjectives. No preamble, method or caveats unless they change the action.
- Detail lives in the monthly doc, linked once at the end as "Details →".
- Hard cap: channel 12 lines. One idea per line.

## Safety

- Read-only on every third party: never submit forms, send email or outreach, sign up, comment, vote or post on Reddit, X, LinkedIn or any social or community site. Draft text for human review only.
- Never change the AI-answer tracker's prompts, monitors, personas, models or schedules.
- Only write posts to `report_channel`, DMs to the configured `owner` only when this skill calls for one, and scoped edits to the named shared docs and sections this skill owns.
- Never @-mention anyone in the channel. Never put credentials, tokens or passwords in posts, docs or DMs.
- Never open PRs, edit the site or change third-party profiles.

## Example configuration

How type.com configures this skill (example):

- Docs: https://docs.type.com. Its sitemap is https://docs.type.com/sitemap-index.xml; /sitemap.xml returned 404 in the Oct 22, 2026 dry run.
- Exact brand: type.com; excluded look-alike: type.ai. Feature topics: integrations, Slack agents, approvals/human-in-the-loop, security, pricing/plans and MCP.
- Report channel: #b-aeo. Owner: Sam. First Tuesday of the month at 10am, America/Los_Angeles.
- The Oct 22 dry run sampled 8 pages, with 3 answering directly and 5 cited by engines in 90 days. It is an actual reduced sample, not the regular 20-page review.
- The dry run found old /code-automations/* docs URLs cited 15 times despite returning short stubs, and a missing approvals/human-in-the-loop page. Historical findings illustrate fixes; they do not define your site's baseline.