microsoft / microsoft/agentrc

feat: add docUrl to readiness criteria and render actionable links in webapp

Open
#101 0 comments 1 reaction 2 assignees View on GitHub

@danielmeppiel is already working on this.

Since Apr 1, 2026.

  • #103 by @copilot-swe-agent — closed without merging
enhancement
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 guide
  • custom-instructions → link to .github/copilot-instructions.md docs
  • mcp-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.jsbuildFixFirst):

  • Add a "Learn more →" link after the reason text when c.docUrl is 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 docUrl link 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 — add docUrl to types
  • packages/core/src/services/readiness/criteria.ts — populate docUrl per criterion
  • packages/core/src/services/readiness/index.ts — propagate docUrl to results
  • packages/core/src/services/visualReport.ts — render links in CLI HTML
  • webapp/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_ICONS map already recognizes apm-config, apm-locked-deps, apm-ci-integration

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.