Feedback wanted: docs-to-code drift reports for TypeScript PRs

[fstepho]

What I'm Looking For

I'm looking for short first reactions to AnchorMap's public h3 demo PR reports.

AnchorMap flags docs-to-code drift in TypeScript PRs before merge. It runs locally as a CLI or GitHub Action. You define the mappings; AnchorMap reports unmapped anchors, stale mappings, and degraded analysis without uploading source.

You do not need to install anything for a first reaction.

Quick Review Path

If you only open one link, start with the new unmapped anchor PR:

• New unmapped anchor: demo: add unmapped AnchorMap preview scenario anchormap-h3-demo#3

The PR body starts with an AnchorMap report summary block. Read that first. It should tell you the policy decision, analysis health, finding shape, and what to judge without opening Checks, reading workflow logs, or downloading artifacts.

Use the passing PR as the clean baseline comparison:

• Passing baseline: demo: clean AnchorMap preview scenario anchormap-h3-demo#2

The other demo PRs show additional failure or warning-style cases:

• Stale mapping: demo: add stale mapping AnchorMap preview scenario anchormap-h3-demo#4
• Degraded analysis: demo: add degraded analysis AnchorMap preview scenario anchormap-h3-demo#5

Checks, job summaries, and artifacts remain available as optional verification context if you want to inspect the generated report more deeply.

Then either comment here or open the first-reaction template:

• https://github.com/fstepho/anchormap/issues/new?template=first-reaction.yml

Useful first-reaction questions:

1. Did you understand the problem AnchorMap is trying to solve?
2. Did the PR body report summary make sense?
3. Would you try this on a TypeScript repo?
4. What stood out or confused you?
5. Time spent: <5 min / 5-20 min / >20 min

A useful answer can be positive or negative. "Not worth trying because..." is useful feedback.

If You Try The Action

Preview inputs:

• Action: fstepho/anchormap-action@v0-preview.4
• CLI: anchormap@1.2.2

Setup docs:

• https://github.com/fstepho/anchormap/blob/main/docs/github-action.md
• https://github.com/fstepho/anchormap/blob/main/docs/design-partner-preview.md
• https://github.com/fstepho/anchormap/blob/main/docs/github-action-demo.md

If you run into a specific issue, please use one of the structured templates:

• Action installation problem
• Confusing PR report
• Policy request
• Design partner feedback

Boundaries

Please do not share private repository files, proprietary specs, secrets, tokens, personal data, internal URLs, or full logs containing secrets.

This issue is for feedback only. It does not authorize release, Marketplace publication, SaaS upload, GitHub App work, PR comment automation, JUnit/SARIF Action work, or bundled Action work.

PREVIEW-3 tracking issue: #4

[juzigu40-ui]

First reaction after reading the README path and PR #3 / #2 / #4 bodies only. I did not install or open artifacts.

1. I understood the problem.

The strongest framing is: "this PR added a spec-like docs claim, but no one mapped it to code, so CI should stop before reviewers assume the claim is covered." That was clear from PR #3.

2. The PR body report mostly makes sense.

The useful parts were:

• Policy decision: FAIL
• Analysis health: clean
• Finding: unmapped_anchor
• the concrete anchor name
• the suggested likely mapping target

That is enough to know what to inspect without opening logs.

3. Main confusion: fail vs degraded.

In PR #3, FAIL + clean means the tool confidently found a policy problem. In PR #4, FAIL + degraded means the tool found a stale mapping and also trust is reduced. I think that distinction is correct, but it may need one sentence in every report:

• clean = analysis was trustworthy; the finding is the issue
• degraded = analysis itself has a trust problem; fix that before interpreting coverage too strongly

Without that, a reviewer may read degraded as a severity level instead of a confidence / health signal.

4. The report needs a smaller reviewer action section.

PR #3 has an Action: line, which is the right idea. I would make it visually separate and always use the same shape:

Reviewer action:
- Decide whether this docs anchor should be enforced.
- If yes, add mapping DOC.CORS.PREFLIGHT_REQUEST_HANDLING -> src/utils/cors.ts.
- If no, remove/downgrade the anchor so CI stops treating it as a covered requirement.

That would make the red check feel less like a static analysis warning and more like a review workflow.

5. I would try it on a TypeScript repo only if setup starts in report-only mode.

The concept is useful, but the risk is CI noise from a first scaffold. I would want the first workflow example to run as:

• generate report
• upload artifact / job summary
• do not fail PRs yet
• promote a small set of anchors
• then enable fail-on-policy

The README mentions scaffolding and promotion, but the demo PRs are all policy scenarios. A "first week rollout" example would reduce hesitation.

Time spent: 5-20 minutes.

[mt211211]

First reaction after reading the no-install path and demo PRs #2–#5. I did not install the Action.

1. The problem became clear once I read PR docs: update GitHub Action preview links #3: a docs claim can look covered to a reviewer even though nobody has explicitly connected it to code. FAIL + clean communicated that confidently.

2. My biggest adoption blocker is the unanswered mapping-overhead question. PR docs: update GitHub Action preview links #3 already says the anchor likely maps to src/utils/cors.ts; my immediate reaction was: if AnchorMap can suggest that file, what judgment still requires a human mapping, and how long does that judgment take on a real repo? One sentence explaining why explicit approval is valuable would make the product feel less like maintenance work.

3. I would make every failing report end with a copyable next action, for example:

Review decision needed: Should this docs claim be enforced?
If yes: anchormap map --anchor DOC.CORS.PREFLIGHT_REQUEST_HANDLING --seed src/utils/cors.ts
If no: mark the anchor as draft or remove it from active specs.

That turns the red check into a two-path review decision rather than another CI finding to decode.

4. The passing baseline undersells the value. Instead of only Findings added: 0, I would show a compact proof line such as 3 active anchors · 3 mapped · 0 drift findings. A clean report should reassure the reviewer that AnchorMap checked something meaningful, not merely stayed quiet.

5. I would try it if the onboarding promise were framed as a bounded pilot: “15 minutes, one docs folder, one TypeScript slice, report-only mode.” The current README is thorough, but the first commercial/adoption question is how quickly I can learn whether my repo has enough useful spec-like docs to justify maintaining mappings.

Time spent: 5–20 minutes.