Skip to content

fix(seo): list brownfield reports and contracts in sitemap and llms.txt #483

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rdmueller merged 2 commits into from
May 14, 2026
Merged

fix(seo): list brownfield reports and contracts in sitemap and llms.txt #483

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7d99dc3
fix(seo): list brownfield reports and contracts in sitemap and llms.txt
raifdmueller May 14, 2026
53901a4
style: prettier-format DOC_PAGES block in generate-llms-txt.js
raifdmueller May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/all-anchors.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,8 @@ include::anchors/what-would-chuck-norris-do.adoc[leveloffset=+2]

== Requirements Engineering

include::anchors/cockburn-use-cases.adoc[leveloffset=+2]

include::anchors/ears-requirements.adoc[leveloffset=+2]

include::anchors/invest.adoc[leveloffset=+2]
Expand Down
83 changes: 83 additions & 0 deletions scripts/generate-llms-txt.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,89 @@ function generateLlmsTxt() {
lines.push('')
}

// Top-level documentation pages (each pre-rendered as a standalone HTML page)
const DOC_PAGES = [
{
title: 'About',
url: 'https://llm-coding.github.io/Semantic-Anchors/about',
summary:
'What semantic anchors are, why they matter for LLM communication, and how the catalog is curated.',
},
{
title: 'Spec-Driven Development',
url: 'https://llm-coding.github.io/Semantic-Anchors/spec-driven-development',
summary:
'Greenfield workflow — from requirements to specification to implementation, powered by semantic anchors.',
},
{
title: 'Brownfield Workflow',
url: 'https://llm-coding.github.io/Semantic-Anchors/brownfield',
summary:
'Applying semantic anchors to brownfield codebases using a bounded-context approach with reverse-engineered safety nets.',
},
{
title: 'Brownfield Experiment 1a Report',
url: 'https://llm-coding.github.io/Semantic-Anchors/brownfield-experiment-report',
summary:
'Controlled experiment: delete documentation from a greenfield project, regenerate from code, compare. Methodology, findings, and the Brownfield Preparation Checklist.',
},
{
title: 'Brownfield Fair Comparison',
url: 'https://llm-coding.github.io/Semantic-Anchors/brownfield-fair-comparison',
summary:
'Three approaches (Direct, Socratic, Two-Phase) compared with identical team answers. Measures the structural value of the Question Tree, not the answers.',
},
{
title: 'Socratic Code-Theory Recovery Skill',
url: 'https://llm-coding.github.io/Semantic-Anchors/socratic-recovery-skill',
summary:
'Installable Claude Code Skill that packages the brownfield documentation-recovery workflow as a two-phase Question Tree with Q-ID traceability.',
},
{
title: 'Semantic Contracts',
url: 'https://llm-coding.github.io/Semantic-Anchors/contracts',
summary:
'Composable contracts that define what terms mean in your project — pick and copy into your AGENTS.md or CLAUDE.md.',
},
{
title: 'AgentSkill',
url: 'https://llm-coding.github.io/Semantic-Anchors/agentskill',
summary:
'The semantic-anchor-translator AgentSkill — install semantic anchors into Claude Code, Codex, Cursor, and other coding agents.',
},
{
title: 'Evaluations',
url: 'https://llm-coding.github.io/Semantic-Anchors/evaluations',
summary: 'Multiple-choice evaluations of semantic anchor recognition across 10 LLMs.',
},
{
title: 'Full Reference',
url: 'https://llm-coding.github.io/Semantic-Anchors/all-anchors',
summary:
'All semantic anchors in one long document — readable offline, linkable, easy to Ctrl-F.',
},
{
title: 'Changelog',
url: 'https://llm-coding.github.io/Semantic-Anchors/changelog',
summary: 'Chronological record of all semantic anchors added to the catalog.',
},
{
title: 'Contributing',
url: 'https://llm-coding.github.io/Semantic-Anchors/contributing',
summary:
'How to propose new semantic anchors, quality criteria, and the contribution workflow.',
},
]

lines.push('## Documentation')
lines.push('')
for (const page of DOC_PAGES) {
lines.push(`- [${page.title}](${page.url}): ${page.summary}`)
}
lines.push('')
lines.push('---')
lines.push('')

Comment thread
coderabbitai[bot] marked this conversation as resolved.
// Anchors by category
for (const category of categories) {
lines.push(`## ${category.name}`)
Expand Down
6 changes: 4 additions & 2 deletions scripts/generate-sitemap.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,6 @@ const BASE_URL = 'https://llm-coding.github.io/Semantic-Anchors'
// shell to non-JS crawlers and claude.ai fetchers.
//
// Excluded on purpose:
// - /contracts — interactive JS page (localStorage, client-side data
// fetching); no static content worth serving
// - /anchor/:id — rendered per entry via the anchor loop below
//
// priority: 1.0 homepage, 0.8 top-level content, 0.7 contributing/meta, 0.6 anchors
Expand All @@ -40,6 +38,10 @@ const PAGES = [
{ path: '/about', priority: '0.8', changefreq: 'monthly' },
{ path: '/spec-driven-development', priority: '0.8', changefreq: 'monthly' },
{ path: '/brownfield', priority: '0.8', changefreq: 'monthly' },
{ path: '/brownfield-experiment-report', priority: '0.7', changefreq: 'monthly' },
{ path: '/brownfield-fair-comparison', priority: '0.7', changefreq: 'monthly' },
{ path: '/socratic-recovery-skill', priority: '0.7', changefreq: 'monthly' },
{ path: '/contracts', priority: '0.7', changefreq: 'monthly' },
{ path: '/evaluations', priority: '0.8', changefreq: 'monthly' },
{ path: '/all-anchors', priority: '0.8', changefreq: 'weekly' },
{ path: '/agentskill', priority: '0.7', changefreq: 'monthly' },
Expand Down
120 changes: 117 additions & 3 deletions website/public/llms.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Semantic Anchors — Complete Reference

> 136 well-defined terms, methodologies, and frameworks
> 137 well-defined terms, methodologies, and frameworks
> that serve as precision reference points when communicating with LLMs.
> Source: https://github.com/LLM-Coding/Semantic-Anchors
> Website: https://llm-coding.github.io/Semantic-Anchors/
Expand All @@ -9,6 +9,39 @@

# About Semantic Anchors

++++
<figure class="youtube-facade-wrapper">
<button
type="button"
class="youtube-facade"
data-video-id="Q_DWMayAQEQ"
data-video-title="LLM Coding with Semantic Anchors: From Vibe Coding to a Real Java App with Ralf D. Müller"
aria-label="Load and play video: LLM Coding with Semantic Anchors — From Vibe Coding to a Real Java App. YouTube only loads on click."
>
<img
src="https://i.ytimg.com/vi/Q_DWMayAQEQ/maxresdefault.jpg"
alt=""
loading="lazy"
/>
<span class="youtube-facade-play">
<span class="youtube-facade-play-icon">
<svg fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
<path d="M8 5v14l11-7z"/>
</svg>
</span>
</span>
<span class="youtube-facade-title">
<strong>LLM Coding with Semantic Anchors — From Vibe Coding to a Real Java App</strong>
<em>YouTube only loads on click (GDPR)</em>
</span>
</button>
<figcaption>
Two-hour live coding session with Johannes Rabauer and Ralf D. Müller (May 2026).
Read Johannes' <a href="https://rabauer.dev/en/blog/semantic-anchors/" target="_blank" rel="noopener noreferrer">session summary on rabauer.dev</a>.
</figcaption>
</figure>
++++

## What are Semantic Anchors?

**Semantic anchors** are well-defined terms, methodologies, and frameworks that serve as reference points when communicating with Large Language Models (LLMs). They act as shared vocabulary that triggers specific, contextually rich knowledge domains within an LLM's training data.
Expand Down Expand Up @@ -307,6 +340,23 @@ Ready to explore? [Browse the catalog →](https://llm-coding.github.io/Semantic

---

## Documentation

- [About](https://llm-coding.github.io/Semantic-Anchors/about): What semantic anchors are, why they matter for LLM communication, and how the catalog is curated.
- [Spec-Driven Development](https://llm-coding.github.io/Semantic-Anchors/spec-driven-development): Greenfield workflow — from requirements to specification to implementation, powered by semantic anchors.
- [Brownfield Workflow](https://llm-coding.github.io/Semantic-Anchors/brownfield): Applying semantic anchors to brownfield codebases using a bounded-context approach with reverse-engineered safety nets.
- [Brownfield Experiment 1a Report](https://llm-coding.github.io/Semantic-Anchors/brownfield-experiment-report): Controlled experiment: delete documentation from a greenfield project, regenerate from code, compare. Methodology, findings, and the Brownfield Preparation Checklist.
- [Brownfield Fair Comparison](https://llm-coding.github.io/Semantic-Anchors/brownfield-fair-comparison): Three approaches (Direct, Socratic, Two-Phase) compared with identical team answers. Measures the structural value of the Question Tree, not the answers.
- [Socratic Code-Theory Recovery Skill](https://llm-coding.github.io/Semantic-Anchors/socratic-recovery-skill): Installable Claude Code Skill that packages the brownfield documentation-recovery workflow as a two-phase Question Tree with Q-ID traceability.
- [Semantic Contracts](https://llm-coding.github.io/Semantic-Anchors/contracts): Composable contracts that define what terms mean in your project — pick and copy into your AGENTS.md or CLAUDE.md.
- [AgentSkill](https://llm-coding.github.io/Semantic-Anchors/agentskill): The semantic-anchor-translator AgentSkill — install semantic anchors into Claude Code, Codex, Cursor, and other coding agents.
- [Evaluations](https://llm-coding.github.io/Semantic-Anchors/evaluations): Multiple-choice evaluations of semantic anchor recognition across 10 LLMs.
- [Full Reference](https://llm-coding.github.io/Semantic-Anchors/all-anchors): All semantic anchors in one long document — readable offline, linkable, easy to Ctrl-F.
- [Changelog](https://llm-coding.github.io/Semantic-Anchors/changelog): Chronological record of all semantic anchors added to the catalog.
- [Contributing](https://llm-coding.github.io/Semantic-Anchors/contributing): How to propose new semantic anchors, quality criteria, and the contribution workflow.

---

## Communication & Presentation

### 4MAT
Expand Down Expand Up @@ -3381,6 +3431,55 @@ GPT-5.3 Codex activates the decisiveness signal but **not** the character voice

## Requirements Engineering

### Cockburn Use Cases

***Full Name***: Cockburn Use Cases (Writing Effective Use Cases)

***Also known as***: Fully Dressed Use Cases, Goal-Level Use Cases, Cockburn Format

[discrete]
## **Core Concepts**:

***Fully Dressed Format***
A structured textual template for describing system behavior from the actor's perspective. Each use case includes: Primary Actor, Stakeholders & Interests, Preconditions, Trigger, Main Success Scenario (numbered steps), Extensions (alternative/failure paths with step references), Postconditions (success guarantee and minimal guarantee), and Technology & Data Variations.

***Goal Levels***
Three abstraction levels that organise use cases into a hierarchy:

* **Summary** (Kite/Cloud) — business-process-level goals spanning multiple user sessions. Example: "Manage customer lifecycle."
* **User Goal** (Sea Level) — the sweet spot: one actor, one sitting, one measurable outcome. Example: "Place an order." Most use cases live here.
* **Subfunction** (Fish/Clam) — steps that support a user goal but are not goals in themselves. Example: "Authenticate user." Extract only when reused across multiple user-goal use cases.

***Scope***
Defines the system boundary — what is inside the "design scope" and what is an external actor. Cockburn uses icons (a box for the system, a person for actors) to make the boundary visual. Getting scope right prevents use cases from being either too vague (organisational scope) or too detailed (component scope).

***Actor-Goal List***
The discovery technique: list every actor and every goal they have against the system. This produces a candidate use case list before writing any prose. The goal level test: "Does the actor go home happy if this goal is achieved?" filters out subfunctions masquerading as user goals.

**What Cockburn does **not** prescribe**
Cockburn's format is deliberately **prose-based and notation-agnostic**. It does not mandate Activity Diagrams, Gherkin, EARS, or any formal syntax. Those are complementary representations that can be layered on top — Activity Diagrams for visual flow, Gherkin for executable acceptance criteria, EARS for structured requirement statements.
Comment on lines +3459 to +3460
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Markdown-Formatierung in Line 3459 ist kaputt.

**What Cockburn does **not** prescribe** ist verschachtelt/falsch betont und rendert inkonsistent. Bitte auf konsistente Hervorhebung umstellen (z. B. **What Cockburn does not prescribe**).

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@website/public/llms.txt` around lines 3459 - 3460, Die fette Überschrift
enthält verschachtelte Sternchen (`**What Cockburn does **not** prescribe**`)
und rendert inkonsistent; ersetze diese Zeichenfolge durch eine konsistente
Hervorhebung wie `**What Cockburn does not prescribe**` (suche nach der genauen
Zeichenkette "What Cockburn does **not** prescribe" im Diff) und überprüfe
angrenzende Markdowns in derselben Zeile/Paragraph (z. B. "**prose-based and
notation-agnostic**") auf ähnliche verschachtelte Asterisk-Fehler, damit die
gesamte Zeile korrekt bolded bzw. formatiert wird.


***Key Proponents***: Alistair Cockburn (_Writing Effective Use Cases_, Addison-Wesley, 2001). The book remains the canonical reference; Cockburn also contributed to the Agile Manifesto and Crystal methodologies.

[discrete]
## **When to Use**:

* Discovering what a system needs to do before deciding how to build it — the Actor-Goal List is a fast, structured brainstorm
* Structuring requirements conversations with stakeholders who think in scenarios, not features
* Decomposing a large system into manageable behavioural units at the right granularity (goal-level test)
* Brownfield theory recovery: reconstructing what a system does by writing use cases from observed behaviour
* Feeding downstream artifacts: each use case becomes a natural unit for Activity Diagrams, Gherkin scenarios, and test plans
* Complementing arc42: use cases populate Section 6 (Runtime View) and inform Section 3 (Context and Scope)

[discrete]
## **Related Anchors**:

* Gherkin - Executable acceptance criteria that can be derived from each extension path in a use case
* BDD Given/When/Then - Formalises the scenario steps that Cockburn describes in prose
* EARS Requirements - Structured syntax for individual requirement statements; complements Cockburn's scenario-level structure
* arc42 - Use cases feed Section 6 (Runtime View) and inform Section 3 (Context and Scope)
* ISO 25010 - Quality goals that use case extensions should address (error handling, performance, security)

### EARS-Requirements

***Full Name***: Easy Approach to Requirements Syntax
Expand Down Expand Up @@ -5537,11 +5636,14 @@ Select and download: https://llm-coding.github.io/Semantic-Anchors/#/contracts
## Specification

When we talk about a "specification" or "spec", we mean:
- Use Cases with Trigger, Main Flow, Alternative Flows, Postconditions, and Business Rules (BR-IDs)
- Persona Use Cases in Cockburn's Fully Dressed format (Primary Actor, Trigger, Main Success Scenario, Extensions, Postconditions) at User Goal level, with Business Rules (BR-IDs)
- System Use Cases for each technical interface (API endpoint, CLI command, event, file format): input/validation, processing, output/status codes, error responses
- Activity Diagrams for all flows (not just the happy path)
- Acceptance criteria in Gherkin format (Given/When/Then)
- Individual requirements in EARS syntax where applicable (When/While/If/Shall)
- Supplementary Specifications as needed: Entity Model, State Machines, Interface Contracts, Validation Rules

*Referenced anchors: gherkin, bdd-given-when-then*
*Referenced anchors: cockburn-use-cases, gherkin, bdd-given-when-then, ears-requirements*

## Requirements Discovery

Expand Down Expand Up @@ -5624,6 +5726,18 @@ Documentation follows Docs-as-Code according to Ralf D. Müller:

*Referenced anchors: docs-as-code, plain-english-strunk-white, gutes-deutsch-wolf-schneider*

## Socratic Code Theory Recovery

Recover a program's "theory" (Naur 1985) from source code through recursive question refinement.
- Start with 5 high-level questions: Problem/Users, Specification, Architecture, Quality Goals, Risks
- Decompose each question using Semantic Anchors as guides: arc42 (12 sub-questions), Cockburn Use Cases, ISO 25010, Nygard ADRs
- Each leaf is either `[ANSWERED]` (with code evidence) or `[OPEN]` (with Category, Ask role, and why unanswerable)
- The Question Tree is the primary artifact; documentation is synthesized from answered leaves
- Open Questions are the handoff document: routed by role (Product Owner, Architect, Developer, Domain Expert, Operations)
- Two-phase workflow: Phase 1 builds the tree, team answers Open Questions, Phase 2 produces documentation with Q-ID traceability

*Referenced anchors: socratic-method, arc42, iso-25010, adr-according-to-nygard, mental-model-according-to-naur*

## Concise Response (TLDR)

Responses lead with the conclusion first (BLUF). Keep to essential points. No filler, no preamble. Use short sentences, active voice, and no unnecessary words (Strunk & White).
Expand Down
Loading
Loading