semantic-web-write

name

semantic-web-write

description

Generate profile-declared HTML artifacts from given data or source material. Use when the user wants a report, explainer, status page, audit, documentation page, or other shareable HTML output that should be readable by humans and interpretable by semantic readers through a declared profile such as ALPS. Trigger when the user asks to write semantic HTML, profile an HTML artifact, create HTML with rel="profile", generate an ALPS-backed page, make data understandable to both people and agents, or produce the write-side counterpart to semantic-web-fetch.

Semantic Web Write

Create HTML whose meaning is declared, not merely implied. The output should be useful to a human reader as an HTML artifact and useful to a semantic reader as raw HTML plus a profile.

Core Contract

Every semantic HTML artifact has two coordinated outputs:

1. HTML document: readable, navigable, static HTML suited to the source data.
2. Profile document: an ALPS profile, or another declared vocabulary when explicitly requested, that defines the meaning of the document's important elements.

The HTML must declare the profile with rel="profile" and bind meaningful elements to descriptor IDs. Do not rely on headings, labels, color, or visual position as the sole source of meaning.

When creating or substantially revising an ALPS profile, use the alps skill from alps-asd/alps-skills as the ALPS authoring authority when it is available. This skill owns the HTML artifact contract; ALPS profile design, validation, and improvement should follow alps-skills rather than duplicating its full guidance here. Validate ALPS profiles with asd --validate <profile> before finalizing whenever asd is available.

When To Use HTML

Use HTML when the result benefits from layout, visual hierarchy, tables, diagrams, anchors, collapsible sections, lightweight interaction, or sharing as a static page. Stay in Markdown for short conversational replies, code-only answers, terminal instructions, or content that is only a few bullets.

For HTML artifact shape and visual judgment, read references/html-artifact-patterns.md when the output is substantial or shared.

For reports derived from public pages, documentation, issue trackers, articles, or datasets, read references/source-backed-reports.md before writing. It covers source links, provenance, citation density, selection depth, language choice, and how to summarize without copying the source.

For substantial artifacts, read references/self-review-gate.md before finalizing. A valid profile link is necessary but not enough; run at least one self-revision pass after validation.

Profile Binding Rules

Before writing final output, decide the document vocabulary:

• Name the document state, such as semanticReport, auditReport, or termUsageIndex.
• Name the recurring parts, such as summary, finding, term, usage, owner, or dueDate.
• Name transitions only when the HTML exposes real affordances, such as goIssue or exportJson.
• Keep decorative content unbound, or explicitly report it as unbound during verification.

Use stable markers that semantic readers can bind:

• Prefer a class matching the descriptor ID, e.g. <section class="summary">.
• Use data-semantic="descriptorId" when a class would be stylistically awkward.
• If an element has multiple classes, make one class exactly match the descriptor ID.
• Keep descriptor IDs stable and case-sensitive.

For detailed binding and profile guidance, read references/profile-binding.md.

Workflow

1. Identify the input data and the reader's job.
2. Choose whether HTML is warranted. If not, answer normally.
3. Define the semantic vocabulary before writing the page.
4. Write or select the ALPS profile, using alps-asd/alps-skills for profile creation or substantial profile improvement when available.
5. Write the HTML with <link rel="profile" href="...">.
6. Bind meaningful elements to descriptor IDs through stable classes or attributes.
7. Run asd --validate <profile> for ALPS profiles when asd is available.
8. Run scripts/validate_profile_bindings.py when writing files locally, or perform the same checks manually when a script cannot be run.
9. Self-review and revise once before finalizing. For substantial artifacts, do a second pass if the first self-review finds gaps in source grounding, vocabulary, hierarchy, or accessibility.
10. Verify the result with the semantic-web-fetch reading model:

• declared structure
• established bindings
• transitions, if any
• unbound elements

Output Expectations

• Produce static files with relative links when writing to disk.
• Avoid required network assets unless the user explicitly wants them.
• Use restrained, durable styling. Default to GitHub/Google-like document pages: simple tables, headings, source links, light rules, system fonts, and little UI chrome.
• Avoid card grids, pill navigation, shadows, rounded panels, decorative badges, gradients, and other UI decoration unless they solve a specific reading or interaction problem.
• Color should carry status, category, severity, or other meaning.
• Do not adapt the visual style to "respect" or dramatize the topic. The default output should be a plain report that remains acceptable years later.
• Use images only when they are source data, evidence, or necessary for identification/comparison; never as decoration.
• Do not make the profile claim trust. It declares meaning; it does not prove that data is true or that an affordance is safe.
• If the output includes controls that mutate local page state, add an export affordance such as "copy JSON" or "copy Markdown" so the user's edits can round-trip.

Local Validation

When the output is written to disk, validate the ALPS profile first, then validate the HTML/profile binding:

asd --validate path/to/report.alps.json

python3 skills/semantic-web-write/scripts/validate_profile_bindings.py \
  path/to/report.html \
  --require semanticReport summary finding sourceLink \
  --require-parent-child semanticReport:finding finding:sourceLink \
  --warn-unused-descriptors \
  --warn-unprofiled-classes

The validator reads the HTML, follows the relative rel="profile" link, extracts ALPS descriptor IDs, and confirms that required descriptors appear in both the profile and the HTML classes or data-semantic attributes. Explicit data-semantic tokens must exist in the profile unless the validator is run with --allow-undefined-data-semantic. Use --require-parent-child when a nested record structure matters, such as workEntry:topic or topic:sourceLink.