feat: add docUrl to readiness criteria and render actionable links in webapp
@danielmeppiel is already working on this.
Since Apr 1, 2026.
- #103 by @copilot-swe-agent — closed without merging
- Dominant language
- TypeScript
- Stars
- 1.1k
- Forks
- 94
- Avg merge
- 8d 3h
- Merged PRs (30d)
- 7
Description
Problem
When a readiness criterion fails (especially APM checks from PR #92), users see the title, reason, and impact/effort badges — but no link to documentation that explains how to fix it. This applies to both the Fix First section and the AI Tooling Readiness section in the webapp.
The core ReadinessCriterionResult type has no URL field today.
Proposal
1. Add docUrl field to core criterion types
In packages/core/src/services/readiness/types.ts, extend both the definition and result types:
// Criterion definition (static metadata)
export type ReadinessCriterion = {
// ...existing fields...
docUrl?: string; // Link to documentation explaining the criterion and how to satisfy it
};
// Criterion result (runtime output)
export type ReadinessCriterionResult = {
// ...existing fields...
docUrl?: string; // Propagated from the criterion definition
};
Usage: docUrl is a stable documentation link that explains what the criterion checks and how to set it up. It is the same whether the criterion passes or fails. Examples:
apm-config→ link to APM setup guidecustom-instructions→ link to.github/copilot-instructions.mddocsmcp-config→ link to MCP configuration docs
2. Populate docUrl for all criteria (priority: APM)
Starting with the three APM criteria merged in PR #92:
| Criterion ID | docUrl target |
|---|---|
apm-config |
APM configuration guide |
apm-locked-deps |
Lockfile / dependency pinning docs |
apm-ci-integration |
CI integration for APM docs |
Then backfill for existing ai-tooling criteria (custom-instructions, mcp-config, custom-agents, copilot-skills) and repo-health criteria as docs become available.
3. Render links in the webapp
Fix First section (webapp/frontend/src/report.js → buildFixFirst):
- Add a "Learn more →" link after the reason text when
c.docUrlis present
AI Tooling Hero (buildAiToolingHero):
- For failing criteria, render the title as a clickable link to
c.docUrl(or append a subtle doc link)
Pillar Details (expandable accordion):
- Show
docUrllink next to each failing criterion
4. Propagate through CLI HTML report
The CLI readiness --html visual report (packages/core/src/services/visualReport.ts) should also render docUrl links for consistency across surfaces.
Affected files
packages/core/src/services/readiness/types.ts— adddocUrlto typespackages/core/src/services/readiness/criteria.ts— populatedocUrlper criterionpackages/core/src/services/readiness/index.ts— propagatedocUrlto resultspackages/core/src/services/visualReport.ts— render links in CLI HTMLwebapp/frontend/src/report.js— render links in Fix First, AI Tooling, Pillar Details
Context
- APM criteria added in PR #92
- Webapp added in PR #90
- The webapp's
AI_ICONSmap already recognizesapm-config,apm-locked-deps,apm-ci-integration
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.