README update
Describe current behavior, never a desired future presented as current state.
Discover the documentation contract
- Locate the relevant README and consumer-owned documentation instructions.
Do not assume one root file or a fixed docs layout.
- Discover the required language, audience, section conventions, ownership
details and generated/manual boundaries.
- Read the existing README and preserve accurate, intentional content.
- If target, language, audience or publication scope remains ambiguous, ask.
Build an evidence map
Inspect only sources that exist and are relevant:
- build and dependency definitions for stack and supported commands
- application code and schemas for interfaces and behavior
- deployment configuration for environments, auth, resources and integrations
- automation for actual CI/CD workflows
- migrations or data definitions for owned data
- observability configuration for verified dashboards, probes and alerts
- maintained documentation for domain purpose, operations and ownership
Find sources by role and content, not by a hardcoded path or stack. Record
support for consequential claims. Ask for product purpose, contact information
or private links that cannot be derived safely.
Choose only useful sections
| Section |
Include when |
| Purpose |
Always; state what the software does and for whom |
| Status or support |
The repository documents lifecycle or ownership |
| Development |
Verified setup, run and test instructions exist |
| Interfaces |
The repository exposes APIs, events, jobs or libraries |
| Data and dependencies |
They materially explain behavior or operation |
| Deployment and configuration |
Readers need it and evidence exists |
| Observability |
Verified dashboards, signals or runbooks exist |
| Architecture visual |
Three or more relationships are clearer visually |
| Further reading |
A maintained document is directly relevant |
Do not add badges, contact channels, dashboards, environment links or
technology lists unless they are verified and useful.
Update workflow
- Compare current text with the evidence map.
- Mark statements as keep, update, remove or unresolved.
- Preserve manual operational knowledge until it is disproven or the user
approves removal.
- Write the smallest coherent update.
- Validate commands and links where feasible, and review the diff for
unsupported claims.
For a new README, start with purpose and the shortest verified path to use or
develop it. Add sections only when evidence and reader need justify them.
Content rules
- Use the consumer's documented language and terminology.
- Prefer stable commands or pointers over copied output that will quickly age.
- Describe interfaces from code or generated contracts, not memory.
- Use service, topic, database, environment and auth names only after discovery.
- Use Mermaid only when it materially clarifies verified relationships.
- Do not duplicate an entire schema, runbook or ADR catalogue.
- Make uncertainty explicit instead of filling gaps with plausible defaults.
Approval boundary
The requested local README edit is allowed. Before publishing, committing,
opening a PR, commenting, or editing other docs, show the diff and get approval.
Grenser
Alltid
- Cross-check consequential statements against current repository evidence.
- Preserve accurate manual content.
- Validate local links and commands proportionally to risk.
Spør først
- Remove substantial manual sections.
- Choose between conflicting product descriptions or language rules.
- Add an unverified private link, owner or contact channel.
- Perform any external write.
Aldri
- Invent endpoints, data stores, auth, environments, owners or dashboards.
- Assume a framework, package, manifest or documentation path.
- Replace a repository-specific README with a generic template.
1---2name: readme-update3description: Create or update a README from verified implementation and operational evidence. Use when repository purpose, setup, usage or ownership documentation is missing or stale; use `klarsprak` for a wording-only edit and `to-spec` for intended future behavior.4---56# README update78Describe current behavior, never a desired future presented as current state.910## Discover the documentation contract11121. Locate the relevant README and consumer-owned documentation instructions.13 Do not assume one root file or a fixed docs layout.142. Discover the required language, audience, section conventions, ownership15 details and generated/manual boundaries.163. Read the existing README and preserve accurate, intentional content.174. If target, language, audience or publication scope remains ambiguous, ask.1819## Build an evidence map2021Inspect only sources that exist and are relevant:2223- build and dependency definitions for stack and supported commands24- application code and schemas for interfaces and behavior25- deployment configuration for environments, auth, resources and integrations26- automation for actual CI/CD workflows27- migrations or data definitions for owned data28- observability configuration for verified dashboards, probes and alerts29- maintained documentation for domain purpose, operations and ownership3031Find sources by role and content, not by a hardcoded path or stack. Record32support for consequential claims. Ask for product purpose, contact information33or private links that cannot be derived safely.3435## Choose only useful sections3637| Section | Include when |38|---|---|39| Purpose | Always; state what the software does and for whom |40| Status or support | The repository documents lifecycle or ownership |41| Development | Verified setup, run and test instructions exist |42| Interfaces | The repository exposes APIs, events, jobs or libraries |43| Data and dependencies | They materially explain behavior or operation |44| Deployment and configuration | Readers need it and evidence exists |45| Observability | Verified dashboards, signals or runbooks exist |46| Architecture visual | Three or more relationships are clearer visually |47| Further reading | A maintained document is directly relevant |4849Do not add badges, contact channels, dashboards, environment links or50technology lists unless they are verified and useful.5152## Update workflow53541. Compare current text with the evidence map.552. Mark statements as keep, update, remove or unresolved.563. Preserve manual operational knowledge until it is disproven or the user57 approves removal.584. Write the smallest coherent update.595. Validate commands and links where feasible, and review the diff for60 unsupported claims.6162For a new README, start with purpose and the shortest verified path to use or63develop it. Add sections only when evidence and reader need justify them.6465## Content rules6667- Use the consumer's documented language and terminology.68- Prefer stable commands or pointers over copied output that will quickly age.69- Describe interfaces from code or generated contracts, not memory.70- Use service, topic, database, environment and auth names only after discovery.71- Use Mermaid only when it materially clarifies verified relationships.72- Do not duplicate an entire schema, runbook or ADR catalogue.73- Make uncertainty explicit instead of filling gaps with plausible defaults.7475## Approval boundary7677The requested local README edit is allowed. Before publishing, committing,78opening a PR, commenting, or editing other docs, show the diff and get approval.7980## Grenser8182### Alltid8384- Cross-check consequential statements against current repository evidence.85- Preserve accurate manual content.86- Validate local links and commands proportionally to risk.8788### Spør først8990- Remove substantial manual sections.91- Choose between conflicting product descriptions or language rules.92- Add an unverified private link, owner or contact channel.93- Perform any external write.9495### Aldri9697- Invent endpoints, data stores, auth, environments, owners or dashboards.98- Assume a framework, package, manifest or documentation path.99- Replace a repository-specific README with a generic template.
navikt