shard-wiki/spec/UseCaseCatalog.md

UseCaseCatalog

Status: draft · Date: 2026-06-08 · Updated: 2026-06-08

Promoted from research/260608-c2-wiki-origins/ and research/260608-yawex-prior-art/. See InfoTechPrimers on coulomb.social for use-case catalog conventions.

Conventions

Each use case lists:

• Actor — who initiates the action
• Goal — observable outcome
• Source — research lineage (c2, yawex, intent, or combined)
• Notes — shard-wiki-specific constraints or open design points

Priority hints: MVP = likely early value; Later = important but not first slice.

---

A. Information space and federation

shard-wiki orchestration scenarios (INTENT + yawex federation seeds).

UC-01 — Standalone open wiki (L0)

Actor: Anonymous contributor
Goal: Read and write wiki pages with full history and no external dependencies.
Source: intent, c2
Notes: Ward Cunningham / c2-style open mode (WhyWikiWorks). Recovery via Git history, not gatekeeping. Aligns with L0 in spec/ArchitectureBlueprint.md. Priority: MVP

UC-02 — Attach a shard to an information space

Actor: Maintainer
Goal: Attach a repository, directory, or other backend as a shard of a root entity.
Source: intent, yawex
Notes: yawex Conf::TestWiki / FriendsWiki foreshadows multiple roots/shards. Preserve shard sovereignty and adapter capability profile.
Priority: MVP

UC-03 — Project a remote shard page locally

Actor: Reader
Goal: View a page from a remote or read-only shard as a local projection with provenance and freshness visible.
Source: intent, yawex
Notes: yawex VIRTUAL state = projection/cache. Lazy projection; no silent mutation.
Priority: Later

UC-04 — Overlay edit on read-only shard

Actor: Author
Goal: Propose changes to a remote/read-only page as overlay, draft, or patch before destructive apply.
Source: intent, yawex
Notes: yawex append/comment workflow; c2 ThreadMode → refactor pattern. Overlay-before-mutation principle.
Priority: Later

UC-05 — Union derived views

Actor: Reader
Goal: Navigate BackLinks, RecentChanges, AllPages, SiteMap, or Search across all attached shards as a federated graph.
Source: intent, c2, yawex
Notes: Present on both c2 (community nerve center) and yawex core pages. BackLinks over the union link-graph is the strongest core candidate; per-shard vs union scope remains open (see UC-19–UC-21).
Priority: Later

UC-06 — Authenticated team wiki (L2+)

Actor: Authenticated principal
Goal: Read and write under role-based authorization with identity from an external provider.
Source: intent, yawex
Notes: yawex htpasswd + per-topic AccessControl is prior art only; shard-wiki delegates authentication, owns authorization (spec/ArchitectureBlueprint.md).
Priority: Later

UC-07 — Detect and reconcile cross-shard divergence

Actor: Maintainer
Goal: Identify when equivalent pages in different shards have diverged and reconcile them under explicit policy.
Source: intent
Notes: Union without erasure — conflicts visible, not hidden.
Priority: Later

---

B. Knowledge work and collaboration

Patterns from c2 social conventions and yawex authoring workflows.

UC-08 — Quick idea capture

Actor: Contributor
Goal: Capture a thought as a page and link to related pages, including ones that do not exist yet.
Source: c2
Notes: c2 incremental and open design principles; Wiki = "quick web." Markdown-first wikilink/red-link extension (yawex TRANSFORM) applies.
Priority: MVP

UC-09 — Sandbox first edit

Actor: New contributor
Goal: Learn editing mechanics in a safe sandbox without affecting production pages.
Source: c2
Notes: c2 WikiWikiSandbox, WelcomeVisitors onboarding path.
Priority: MVP

UC-10 — Discussion to consensus document

Actor: Contributor (often acting as WikiMaster)
Goal: Refine a ThreadMode conversation into an unsigned DocumentMode page that reflects community consensus.
Source: c2
Notes: ADD / EDIT / SPLIT / CAPTURE thread contributions; prefer rewrite over stacked clarifications (DocumentMode, GoodStyle). Mechanism in core vs reference UI TBD.
Priority: Later

UC-11 — Distill experience into reusable knowledge

Actor: Practitioner
Goal: Turn field notes, threads, or project experience into durable, reusable artifacts (patterns, methods, checklists).
Source: c2, yawex
Notes: c2 PatternMode, PPR "People, Projects & Patterns"; yawex blueprint pages (UC-15). Not an encyclopedia (WikiIsNotWikipedia).
Priority: Later

UC-12 — Practitioner field notes

Actor: Contributor
Goal: Maintain informal, subjective programming and project history that is explicitly work-in-progress.
Source: c2
Notes: InformalHistoryOfProgrammingIdeas, WorkInProgress. Complements UC-11; distinct from reference-grade documentation in docs/ or spec/.
Priority: MVP

UC-13 — Community presence

Actor: Visitor
Goal: Signal participation and discover who is active in the information space.
Source: c2
Notes: c2 RecentVisitors, PeopleIndex. Optional attribution at L1+ (ArchitectureBlueprint L1 Attributed mode).
Priority: Later

UC-14 — Self-curating knowledge base

Actor: Community
Goal: Improve collective quality through open editing, refactoring, and convergent deduplication rather than gatekeeping.
Source: c2
Notes: WhyWikiWorks, RefactorDontDelete, Convergent design principle. shard-wiki adds Git history as structural safety net beyond social norms.
Priority: MVP

UC-15 — Create page from blueprint

Actor: Author
Goal: Instantiate a new page or topic structure from a template, duplicating an agreed layout or subtree.
Source: yawex
Notes: yawex blueprint pages. Distinct from UC-08 (blank capture) and UC-10 (refactoring existing discussion).
Priority: Later

UC-16 — Append or comment without full edit

Actor: Author
Goal: Add material to a page without replacing the entire body — lightweight patch, comment, or append workflow.
Source: yawex, c2
Notes: yawex append/comment; c2 ThreadMode ADD. Maps to overlay model (UC-04) for read-only/remote shards; direct append where adapter allows.
Priority: Later

---

C. Discovery and navigation

Derived views and browse patterns from c2 and yawex.

UC-17 — Change radar

Actor: Reader or maintainer
Goal: See what changed recently across pages and who changed it.
Source: c2, yawex
Notes: c2 RecentChanges, QuickChanges, RecentChangesJunkie; yawex RecentChanges core page. Union scope in UC-05; this UC covers the user need at any scope.
Priority: MVP

UC-18 — BackLinks navigation

Actor: Reader
Goal: Find pages that link to the current page.
Source: c2, yawex
Notes: Link-graph query. Strong core candidate for federated union (UC-05).
Priority: Later

UC-19 — All pages and site map browse

Actor: Reader
Goal: Survey the full page inventory or hierarchical site structure.
Source: c2, yawex
Notes: yawex AllPages, SiteMap core pages; c2 WikiList, categories, RoadMaps. Namespace/path model affects presentation (UC-22).
Priority: Later

UC-20 — Full-text search

Actor: Reader
Goal: Find pages by content keyword or phrase.
Source: c2, yawex
Notes: yawex SearchPage; c2 FindPage, SearchHelper. Core vs adapter-provided indexing TBD.
Priority: Later

UC-21 — Serendipitous browse

Actor: Reader
Goal: Discover unexpected relevant pages without a specific search target.
Source: c2
Notes: RandomPages, VisualTour, LikePages, StartingPoints.
Priority: Later

UC-22 — Namespace and path navigation

Actor: Reader or author
Goal: Resolve and navigate pages using relative (../), absolute (/), and normalized paths within a topic hierarchy.
Source: yawex
Notes: yawex topics-as-directories; page-resolution state space is inspiration only for federation design (not inherited as API).
Priority: Later

UC-23 — Soft topic creation via red link

Actor: Author
Goal: Follow a link to a nonexistent page and create it on first write.
Source: c2, yawex
Notes: c2 PageName?; yawex red-? link semantics. TRANSFORM to CommonMark wikilink + red-link extension.
Priority: MVP

---

D. Provenance and page metadata

yawex Page::info and c2 attribution norms.

UC-24 — Inspect page provenance

Actor: Reader
Goal: See source shard, modification time, freshness, editor attribution, edit count, and whether the page has local overlays or diverges elsewhere.
Source: yawex, c2, intent
Notes: yawex Page::info; c2 optional UserName signing. INTENT explicit provenance principle.
Priority: Later

UC-25 — Collaborative glossary and precise naming

Actor: Community
Goal: Build a shared vocabulary of precise page titles and linked terms that reduce ambiguity across the information space.
Source: c2, yawex
Notes: c2 flat namespace + WikiWord / Precise principle; yawex CamelCase and [[free links]]. Markdown-first link semantics TBD.
Priority: Later

---

Traceability

UC	c2 research	yawex research	INTENT
UC-01	✓		✓
UC-02		✓	✓
UC-03		✓	✓
UC-04	✓	✓	✓
UC-05	✓	✓	✓
UC-06		✓	✓
UC-07			✓
UC-08	✓
UC-09	✓
UC-10	✓
UC-11	✓	✓
UC-12	✓
UC-13	✓
UC-14	✓		✓
UC-15		✓
UC-16	✓	✓
UC-17	✓	✓
UC-18	✓	✓
UC-19	✓	✓
UC-20	✓	✓
UC-21	✓
UC-22		✓
UC-23	✓	✓
UC-24	✓	✓	✓
UC-25	✓	✓

c2 synthesis mapping

Research ID	Catalog UC
UC-C2-01 Quick idea capture	UC-08
UC-C2-02 Collaborative glossary	UC-25
UC-C2-03 Discussion → consensus doc	UC-10
UC-C2-04 Pattern mining	UC-11
UC-C2-05 Community guest book	UC-13
UC-C2-06 Change radar	UC-17
UC-C2-07 Self-curating knowledge base	UC-14
UC-C2-08 Sandbox learning	UC-09
UC-C2-09 Serendipitous browse	UC-21
UC-C2-10 Practitioner field notes	UC-12
UC-C2-11 Team memory for methods	UC-11, UC-12
UC-C2-12 Soft creation of missing topics	UC-23

yawex KEEP mapping

yawex KEEP item	Catalog UC
Derived views (BackLinks, RecentChanges, AllPages, SiteMap, Search)	UC-05, UC-17–UC-20
Topic = namespace hierarchy	UC-22
Append/comment workflow	UC-04, UC-16
Blueprint pages	UC-15
Provenance hooks	UC-24
Page classes (local/global/virtual)	UC-02, UC-03 (shard roles)
Wikilink / red-link semantics	UC-08, UC-23, UC-25

---

Open questions

1. Which UC items are MVP for L0 standalone vs requiring federation or L2+?
2. Which derived views (UC-05, UC-17–UC-20) are core orchestrator vs adapter-provided?
3. Do c2 collaboration patterns (UC-10, UC-14) belong in core, reference UI, or wiki/ social convention only?
4. Should UC-12 and WikiIsNotWikipedia be elevated into ProductRequirementsDocument.md as explicit product identity?