docs-map

Analyse a tool’s online documentation and map it against the feature model dimensions. This is the documentation-only counterpart of codebase-map — use it when the tool is closed-source or proprietary and only online docs are available.

Inputs

The user provides:

1. A single entry-point URL to the tool’s documentation (e.g., https://www.ibm.com/docs/en/mono2micro).
2. A tool name (derive from context or ask the user if not obvious).

Output files

Three files are produced per tool:

1. evaluation/analyses/<tool-name>/analysis.md — filled Analysis Template, feature coverage table, Observations
2. evaluation/analyses/<tool-name>/README.md — documentation sources log, how to set up and run the tool, gotchas, pointer to the colour profile
3. feature_model/representation/.profiles/<tool-name>.profile — FeatureIDE colour profile for the canonical feature model

Never modify my_paper/text.md, feature_model/representation/feature_model.xml, any existing analysis, or any existing profile.

“Existing analysis” and “existing profile” mean files present in the working tree right now. Do not consult git, HEAD, or repository history to decide whether a file exists — judge only by what is on disk. If the user has deleted a tool’s analysis/README/profile locally to re-run the skill, those files do not exist and must be regenerated freely (overwrite is expected). Only refuse to modify analysis/profile files for other tools that are still present on disk.

Procedure

Step 1 — Fetch and explore the documentation entry point

Fetch the landing page using WebFetch(<entry-point URL>). If WebFetch returns an HTTP error (403, 401, 429, 5xx) or an empty/blocked response, fall back immediately to curl via Bash:

strip_html() {
  python3 -c "
import sys, re, html
text = sys.stdin.read()
text = re.sub(r'<[^>]+>', ' ', text)
text = html.unescape(text)
text = re.sub(r'\s+', ' ', text).strip()
print(text)
"
}
curl -s "<url>" -H "Accept: text/html" | strip_html

Use the same curl | strip_html pattern for every subsequent sub-page fetch whenever WebFetch has already failed once for the same domain. Do not retry WebFetch after confirming the domain blocks it.

From the landing page, identify and fetch relevant sub-pages. Prioritise pages that describe:

• What the tool does (overview, architecture, features)
• What inputs it takes (getting started, prerequisites, configuration)
• What algorithms or techniques it uses (how it works, technical overview)
• What outputs and metrics it produces (results, evaluation, API reference)
• Known limitations or caveats (FAQ, known issues, release notes)

Fetch each relevant sub-page individually. Keep a running list of every URL visited (entry-point + all sub-pages fetched), in the order they were fetched. This list will go into the README.

Step 2 — Identify feature model coverage

For each feature model dimension, search the fetched documentation for evidence of support.

Key dimensions to investigate (see references/feature-model-dimensions.md for the full schema):

Granularity: What unit does the tool decompose? Look for terms like class, method, entity, service, package, endpoint, file.

Representation Collection:

• What sources does it read? (source code files, DB schemas, logs, configs)
• What technique? (AST parsing → static; log/trace analysis → dynamic; git history → version)

Representation (Syntax):

• What graph/model is built? (call graph, dependency graph, co-change graph)
• Is it structural, behavioural, or evolution-based?

Refactorization:

• What clustering/decomposition algorithms are used?
• Is there any manual editing support?
• What aggregation criteria drive the clustering?

Quality Assessment:

• What metrics are computed? (coupling, cohesion, MoJoFM, etc.)
• Is there any visual comparison support?

Also check for cross-tree constraint violations (see references/feature-model-dimensions.md). The most common one: Community detection → NOT Expert knowledge. Flag any violations in both the analysis and the colour profile. A violation occurs when the tool uses both features together despite the constraint forbidding it, or when the tool uses a feature without the other feature that must co-exist with it (e.g., dynamic analysis requires runtime).

Also look actively for model gap candidates — capabilities described in the docs that have no counterpart in the feature model schema. For each one, note: what it is, where it appears (URL + quote), whether it would be a leaf or group and under which parent. Pay particular attention to:

• Manual Editing operations beyond Merge/Split/Transfer (e.g., Rename cluster, Form cluster from selection)
• Quality Assessment metrics beyond the listed ones (e.g., silhouette score, purity against expert)
• Refactorization post-processing steps not covered (e.g., contract generation, export)
• Representation sources or collection techniques not in the schema
• Visualisation capabilities not covered by Relations or Visualization Elements

Step 3 — Fill the Analysis Template

Read references/analysis-template.md and fill every section with findings from the documentation. Use bullet points. Every finding must cite at least one URL reference.

Evidence format for docs-map (in order of preference):

1. Direct quote: `<url> — "exact quote from the page"` — always preferred when the documentation contains explicit technical detail.
2. Paraphrase: `<url> — paraphrase: summary of what the page says` — use only when no quotable sentence exists; label explicitly as paraphrase.
3. No evidence: write [evidence not found].

Confidence rule: Prefer Unclear over Yes when the only evidence is a vague marketing claim (e.g., “supports X” with no technical detail). Reserve Yes for documentation that includes technical specifics (algorithm names, config keys, data structures, step-by-step descriptions, screenshots of UI).

Never invent evidence. If a feature is not mentioned in the documentation, mark it absent.

Step 4 — Build the feature coverage table

Produce a table with every leaf feature from the model:

Use Unclear when there is indirect or vague evidence but no direct technical confirmation.

Step 5 — Write the Observations section

Add a section with the following subsections:

Model Gap Candidates — capabilities present in the documentation that have no counterpart in the feature model. For each candidate use this format:

• Name — what it would be called as a feature
• Would be: leaf or group, and the parent dimension/group it would sit under
• Evidence: <url> — "quote"
• Rationale: one sentence on why it warrants a place in the model

Other features outside the model — features present in the documentation but not captured by the feature model and not meeting the criteria to be a model gap candidate (too specific, too low-level, or out of scope). For each one, note what it is and where it appears.

Model Vocabulary Fit — dimensions where the model’s vocabulary doesn’t quite match the tool’s design (concept mismatch, partial overlap, etc.).

Cross-tree constraint violations — features that are used together but the model forbids it (or mandatory co-features that are missing).

Noteworthy design decisions — interesting patterns, architectural choices, or limitations worth mentioning in the paper’s evaluation narrative.

Step 6 — Write analysis.md

Create evaluation/analyses/<tool-name>/ and write analysis.md with sections:

# Analysis — <tool-name>

Documentation: <entry-point URL>
Date: <today's date>

---

## Filled Analysis Template
[content from Step 3]

---

## Feature Coverage Table
[table from Step 4]

---

## Observations

### Model Gap Candidates
[candidates from Step 5]

### Other features outside the model
[list from Step 5]

### Model Vocabulary Fit
[vocabulary notes from Step 5]

### Cross-tree constraint violations
[violations from Step 5, or "None found."]

### Noteworthy design decisions
[design notes from Step 5]

Step 7 — Write README.md

Write evaluation/analyses/<tool-name>/README.md with the following structure:

# <Tool Name>

<one-line description — tool purpose, URL, year if known>

## Relevant Files

| File | Description |
|------|-------------|
| [analysis.md](./analysis.md) | Feature model coverage analysis |
| [feature_model/representation/.profiles/<tool-name>.profile](../../feature_model/representation/.profiles/<tool-name>.profile) | FeatureIDE colour profile |

---

## Documentation Sources

- **Entry point:** <entry-point URL>
- **Fetched:** <today's date>
- **Pages visited:** <total count>

| # | URL | Purpose |
|---|-----|---------|
| 1 | <url> | Entry point / overview |
| 2 | <url> | Getting started / prerequisites |
| 3 | <url> | ... |

---

## Prerequisites
...

## How to Run
...

## Gotchas
...

Relevant Files notes:

• No codebase row (docs-map is used for closed-source/proprietary tools with no local codebase).
• No tool inventory row (docs-map tools are not typically included in survey inventory files — omit unless one exists).
• If a paper PDF is available locally, add a row: | [<Paper title>](../../papers/.../<file>.pdf) | Paper PDF |.

Documentation Sources: List every URL fetched during Step 1, in the order they were visited, with a one-line description of what each page covers.

Step 8 — Write the colour profile

Write feature_model/representation/.profiles/<tool-name>.profile. If this file is not on disk, write it — do not check git/HEAD first; a missing-on-disk profile is meant to be (re)generated.

The profile format is a flat key=value text file. The first line must be false. Feature names must match exactly the leaf and group names in feature_model/representation/feature_model.xml.

Colour scheme — leaves:

Note: Dark_Green is only valid for group nodes, never for leaves.

Documentation-specific rule: Prefer Magenta over Light_Green whenever the only evidence is a high-level marketing claim with no technical detail. Reserve Light_Green for documentation that includes specifics (algorithm names, config keys, data structures, step-by-step descriptions).

Uncertainty rule: When you are unsure whether a piece of documentation refers to the feature at all (ambiguous scope, overlapping terminology, indirect reference), prefer Magenta over Yellow. Use Yellow only when you are confident the feature is absent.

Colour scheme — groups (non-leaf nodes):

Rules for propagating colour up to groups (priority: Red > Orange > Magenta > Light_Green > Yellow):

1. Evaluate each child first.
2. If the group is mandatory and any mandatory child is Red → group is Red.
3. Else if any child is Orange → group is Orange.
4. Else if any mandatory child is Magenta — or, for an OR group, the only present child(ren) are Magenta (every confirmed branch is absent/Red) → group is Magenta. Uncertainty in a required child propagates up; confirmed sibling leaves do not rescue the group.
5. Else if ≥1 mandatory child is confirmed present (Light_Green/Dark_Green) — or, for an OR group, ≥1 child is confirmed present — and no mandatory child is missing or Magenta → group is Light_Green (OR) or continue evaluating (AND).
6. For AND groups: if all mandatory children are fully satisfied and no violations → Dark_Green. A child is fully satisfied when it is a leaf that is present (Light_Green — a leaf’s max, since leaves are never Dark_Green) or a group that is itself Dark_Green. A mandatory child group that is only Light_Green (partially satisfied) caps the AND parent at Light_Green. (Optional children that are absent or Magenta do not block Dark_Green; an optional Red/Orange child still applies rule 2/3.)
7. Optional group with zero present children → Yellow.

Include every leaf and group feature name from feature_model/representation/feature_model.xml. End the file with the following legend keys:

featureColorMeaning0=Leaf/Group: absent or broken (mandatory)
featureColorMeaning1=Constraint violation
featureColorMeaning2=Leaf/Group: absent (optional)
featureColorMeaning3=Group: fully satisfied
featureColorMeaning4=Leaf: exists / Group: partially satisfied
featureColorMeaning5=Extra Feature
featureColorMeaning6=InvalidColor (unused in FeatureIDE)
featureColorMeaning7=InvalidColor (unused in FeatureIDE)
featureColorMeaning8=Leaf: unclear / indirect evidence
featureColorMeaning9=InvalidColor (unused in FeatureIDE)

Step 9 — Report to the user

Summarise:

• How many documentation pages were fetched and which entry point was used
• Which dimensions had strong coverage vs. gaps
• Any constraint violations found
• Anything particularly noteworthy from the Observations
• Paths to the three output files

Key differences from codebase-map

Reference files

• references/feature-model-dimensions.md — full feature model schema with cross-tree constraints
• references/analysis-template.md — the template to fill in Step 3
• feature_model/representation/feature_model.xml — canonical feature model (leaf names for the colour profile)
• feature_model/representation/.profiles/ — existing profiles for reference on format