coulomb/marki-docx
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
e6232395950fc0d44aff41b21bcfd720acd1d486
marki-docx/specs/MarkiDocxUseCaseCatalog_v0.1.md
tegwick c6dfc9b172 chore: workplan MRKD-WP-0001 + improved CLAUDE.md; document next steps 
- workplans/MRKD-WP-0001-foundation-level1.md: 8-task workplan for
  Foundation & LEVEL1 Core (T01 scaffolding through T08 e2e harness)
- CLAUDE.md: added Planned Architecture section (interface table, FR
  domain map, key concepts, round-trip data flow) and Development
  Commands stubs derived from FRS v0.2
- problems/next-steps-2026-03-14.md: implementation guide for next
  session — task order, dep list, state-hub task UUIDs, quality gates

No code implemented yet; workstream registered in State Hub.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-14 18:18:54 +01:00

1413 lines
40 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# UCC
*Use Case Catalog*
# Use Case Catalog: markidocx
**System Scope:** markidocx
**Artifact Type:** Use Case Catalog
**Purpose:** Structured catalog of actor-goal-centered use cases for the markidocx round-trip editing system
**Status:** Draft
**Version:** 1.0
**Parent Artifacts:** PRD markidocx, FRS markidocx
---
# 1. Definition
This Use Case Catalog defines the externally observable functional behavior of **markidocx** from the perspective of its actors.
markidocx enables controlled **Markdown ↔ DOCX round-trip editing** with support for:
* local CLI usage
* REST-based service interaction
* MCP-based agent interaction
* template/style-driven document generation
* multi-file composition
* feature-level processing
* validation and drift detection
* end-to-end regression based on the latest stable markidocx documentation corpus
This catalog organizes the major actor goals that the system must support and provides structured use case descriptions suitable for traceability into the FRS and acceptance artifacts.
---
# 2. Context
markidocx sits between structured Markdown authoring and Word-centric editorial collaboration.
Its main functional challenge is not simple format conversion, but **managed round-trip behavior** under defined semantic constraints.
The catalog therefore focuses on use cases where actors need to:
* define a document project
* inspect and validate project readiness
* build review artifacts
* import edited DOCX files back into Markdown
* preserve or recover structure in multi-file projects
* apply template/style families
* detect drift
* automate workflows through service interfaces
* access the system through agentic tooling
This UCC is positioned between product goals and detailed functional requirements.
---
# 3. Actor Model
## 3.1 Primary Actors
### A-01 Document Author
A person maintaining canonical Markdown sources and preparing documents for export, review, and re-import.
### A-02 Technical Editor
A person responsible for document quality, structure, and consistency across editing cycles.
### A-03 Reviewer
A stakeholder who edits or comments on generated DOCX artifacts, usually without direct interaction with Markdown sources.
### A-04 Build Operator
A person or automation operator invoking builds, validations, or regression flows locally or in controlled environments.
### A-05 Integration Client
An external system calling the REST interface to validate, build, import, compare, or register artifacts.
### A-06 MCP Client
An agentic tool using the MCP interface to inspect projects, trigger operations, and retrieve results.
### A-07 Template Administrator
A person responsible for registering, updating, or governing templates and styles.
### A-08 Release Manager
A person or automation responsible for release validation using the stable documentation corpus as end-to-end testcase.
---
## 3.2 Supporting Actors
### SA-01 Template Registry
Logical externalized registry of available built-in and registered template/style families.
### SA-02 Diagram Renderer
A rendering toolchain used for automatic diagrams in LEVEL3 workflows.
### SA-03 Bibliography Processor
A citation/bibliography-capable processor used in bibliography-aware workflows.
### SA-04 File System / Artifact Store
A storage context for source bundles, generated artifacts, imports, and reports.
### SA-05 Source Mapping Context
A project-specific mapping context allowing re-association of imported content to original source boundaries.
---
# 4. Use Case Levels
The catalog uses three abstraction levels:
* **Summary** – broad actor goals spanning multiple interactions
* **User-goal** – complete actor goals that produce meaningful results
* **Subfunction** – reusable lower-level interactions supporting user goals
The primary catalog emphasis is on **user-goal** use cases.
---
# 5. Catalog Index
| ID | Name | Level | Primary Actor | Goal |
| ------ | ------------------------------------------- | ----------: | ---------------------- | ---------------------------------------------------------------------- |
| UC-001 | Define document project | User-goal | Document Author | Declare a document project usable by markidocx |
| UC-002 | Inspect project configuration | User-goal | Document Author | Understand the resolved structure and capabilities of a project |
| UC-003 | Validate project readiness | User-goal | Build Operator | Determine whether a project is functionally ready |
| UC-004 | Build DOCX review artifact | User-goal | Document Author | Produce a DOCX artifact from Markdown sources |
| UC-005 | Build using alternate family | User-goal | Technical Editor | Export the same source using article, book, or website family |
| UC-006 | Import edited DOCX into Markdown | User-goal | Document Author | Re-import reviewed DOCX content into Markdown-compatible form |
| UC-007 | Round-trip single-file document | Summary | Document Author | Complete a full single-file Markdown → DOCX → Markdown cycle |
| UC-008 | Round-trip multi-file document | Summary | Technical Editor | Complete a full multi-file round-trip cycle with source-aware handling |
| UC-009 | Redistribute imported edits to source files | User-goal | Technical Editor | Re-associate imported content with original source files |
| UC-010 | Fallback to merged Markdown import | User-goal | Technical Editor | Recover usable Markdown when source redistribution is ambiguous |
| UC-011 | Detect round-trip drift | User-goal | Technical Editor | Compare baseline and imported content for semantic drift |
| UC-012 | List available families | User-goal | Template Administrator | Discover built-in and registered template/style families |
| UC-013 | Register additional template family | User-goal | Template Administrator | Add a new template/style family to the system |
| UC-014 | Build LEVEL1 document | User-goal | Document Author | Produce and round-trip a document using LEVEL1 features |
| UC-015 | Build LEVEL3 document | User-goal | Technical Editor | Produce and round-trip a document using LEVEL3 features |
| UC-016 | Generate automatic diagrams | Subfunction | Document Author | Include rendered diagrams derived from source declarations |
| UC-017 | Process bibliography-aware document | Subfunction | Technical Editor | Include citations and bibliography during build/import workflows |
| UC-018 | Execute local CLI workflow | Summary | Build Operator | Perform markidocx operations through the CLI |
| UC-019 | Execute REST-based workflow | Summary | Integration Client | Perform markidocx operations through the REST service |
| UC-020 | Execute MCP-based workflow | Summary | MCP Client | Perform markidocx operations through MCP tools |
| UC-021 | Run end-to-end regression on stable docs | User-goal | Release Manager | Validate latest stable markidocx documentation as canonical testcase |
| UC-022 | Review warning and ambiguity report | User-goal | Technical Editor | Inspect unsupported, degraded, or ambiguous outcomes |
| UC-023 | Retrieve system capability metadata | User-goal | Integration Client | Discover supported feature levels and interfaces |
| UC-024 | Retrieve health and version status | User-goal | Build Operator | Determine operational availability and version state |
| UC-025 | Build and inspect release evidence | User-goal | Release Manager | Produce auditable build/import/diff evidence for a release |
---
# 6. Cross-Reference Map
* **UC-007 Round-trip single-file document** includes UC-003, UC-004, UC-006, UC-011
* **UC-008 Round-trip multi-file document** includes UC-002, UC-003, UC-004, UC-006, UC-009 or UC-010, UC-011
* **UC-015 Build LEVEL3 document** includes UC-016 and UC-017 where applicable
* **UC-018 Execute local CLI workflow** varies UC-003, UC-004, UC-006, UC-011, UC-012, UC-013, UC-021
* **UC-019 Execute REST-based workflow** varies UC-003, UC-004, UC-006, UC-011, UC-023, UC-024
* **UC-020 Execute MCP-based workflow** varies UC-002, UC-003, UC-004, UC-006, UC-011, UC-023
---
# 7. Detailed Use Cases
---
## UC-001 Define document project
**Level:** User-goal
**Primary Actor:** Document Author
**Supporting Actors:** File System / Artifact Store
**Goal:** Create a valid project definition that markidocx can process
### Preconditions
* The actor has a set of Markdown sources or intends to create one
* The actor knows the intended document type and feature level
* Required source files are accessible
### Guarantees
**Success**
* A project definition exists
* The project declares source files, feature level, and selected family references
* The project can be submitted for inspection or validation
**Minimal**
* No existing project data is modified unintentionally
### Main Success Scenario
1. The actor provides a project definition for a document set.
2. The system reads the provided manifest content.
3. The system recognizes declared sources, feature level, and family references.
4. The system acknowledges the project as a recognizable markidocx project.
5. The actor can proceed with inspection or validation.
### Extensions
* **3a.** A referenced source is missing.
The system reports the missing resource.
* **3b.** The manifest contains unsupported settings.
The system reports invalid or unsupported configuration.
* **4a.** Template or style references cannot be resolved.
The system reports unresolved family references.
### Special Requirements
* The use case must remain independent of interface channel
* The project definition must be reusable across CLI, REST, and MCP workflows
---
## UC-002 Inspect project configuration
**Level:** User-goal
**Primary Actor:** Document Author
**Goal:** View the resolved structure and effective capabilities of a project
### Preconditions
* A recognizable project definition exists
### Guarantees
**Success**
* The actor receives a resolved view of project structure
* The actor can see source ordering, family selection, and effective feature level
**Minimal**
* The project remains unchanged
### Main Success Scenario
1. The actor requests inspection of a project.
2. The system resolves the project definition.
3. The system determines the effective source ordering.
4. The system determines selected family and declared capability level.
5. The system returns inspection output to the actor.
### Extensions
* **2a.** The project cannot be resolved.
The system reports why inspection cannot proceed.
* **4a.** Registered family metadata is incomplete.
The system reports incomplete capability resolution.
### Related Use Cases
* UC-003 Validate project readiness
* UC-008 Round-trip multi-file document
---
## UC-003 Validate project readiness
**Level:** User-goal
**Primary Actor:** Build Operator
**Goal:** Determine whether a project is functionally ready for processing
### Preconditions
* A project definition exists
### Guarantees
**Success**
* The actor receives a validation result
* Blocking and non-blocking issues are distinguished
* Functional readiness is made explicit
**Minimal**
* The project remains unchanged
### Main Success Scenario
1. The actor submits a project for validation.
2. The system checks manifest consistency.
3. The system checks referenced resources.
4. The system checks feature-level and family compatibility.
5. The system determines readiness status.
6. The system returns validation output.
### Extensions
* **2a.** The manifest is malformed.
The system reports validation failure.
* **3a.** A required resource is unavailable.
The system reports a blocking issue.
* **4a.** The selected family does not support the declared feature level.
The system returns a compatibility failure.
* **5a.** Non-blocking issues exist.
The system returns a warning state rather than outright failure.
### Related Use Cases
* UC-004 Build DOCX review artifact
* UC-021 Run end-to-end regression on stable docs
---
## UC-004 Build DOCX review artifact
**Level:** User-goal
**Primary Actor:** Document Author
**Supporting Actors:** Template Registry, File System / Artifact Store
**Goal:** Generate a DOCX artifact from the project’s Markdown sources
### Preconditions
* The project is valid or sufficiently processable
* The selected template family is available
### Guarantees
**Success**
* A DOCX artifact is generated
* Declared project content is included according to supported features
* Build status and artifact metadata are returned
**Minimal**
* No existing canonical Markdown source is altered
### Main Success Scenario
1. The actor requests a DOCX build for a project.
2. The system resolves the project structure.
3. The system composes the Markdown sources.
4. The system resolves the selected template/style family.
5. The system applies supported processing for the declared feature level.
6. The system generates a DOCX artifact.
7. The system returns the artifact reference and build report.
### Extensions
* **2a.** The project cannot be resolved.
The system reports a build failure.
* **4a.** The selected family is unavailable.
The system reports an unresolved family reference.
* **5a.** A supported asset cannot be resolved.
The system returns a warning or failure depending on severity.
* **6a.** Build output is generated with degradations.
The system returns the artifact with warnings.
### Related Use Cases
* UC-005 Build using alternate family
* UC-014 Build LEVEL1 document
* UC-015 Build LEVEL3 document
---
## UC-005 Build using alternate family
**Level:** User-goal
**Primary Actor:** Technical Editor
**Goal:** Build the same source content using a different built-in or registered family
### Preconditions
* A project definition exists
* More than one compatible family is available or known
### Guarantees
**Success**
* The actor receives an output artifact built using the selected alternate family
* Canonical content remains unchanged
**Minimal**
* No incompatible family is silently applied
### Main Success Scenario
1. The actor chooses an alternate family for the build.
2. The system resolves the requested family.
3. The system checks capability compatibility.
4. The system builds the document using the selected family.
5. The system returns the resulting artifact and build report.
### Extensions
* **2a.** The requested family is unknown.
The system reports the family cannot be resolved.
* **3a.** The requested family is incompatible with the project’s feature level.
The system returns a compatibility failure.
### Related Use Cases
* UC-012 List available families
* UC-013 Register additional template family
---
## UC-006 Import edited DOCX into Markdown
**Level:** User-goal
**Primary Actor:** Document Author
**Supporting Actors:** Source Mapping Context, File System / Artifact Store
**Goal:** Import an edited DOCX into Markdown-compatible output
### Preconditions
* A DOCX document exists for import
* If source-aware import is expected, a project context exists
### Guarantees
**Success**
* The system produces Markdown-compatible import output
* Supported structure is preserved
* Import warnings and ambiguities are disclosed
**Minimal**
* Existing source content remains unchanged unless the actor deliberately applies imported output later
### Main Success Scenario
1. The actor submits a DOCX file for import.
2. The system recognizes the import request context.
3. The system extracts supported document content.
4. The system maps recognized content into Markdown-compatible representation.
5. The system applies project-aware or source-aware mapping when available.
6. The system produces import output and reports.
7. The actor receives the output and related warnings or mapping status.
### Extensions
* **2a.** No project context is provided.
The system produces a valid import result without project-aware redistribution.
* **3a.** The DOCX contains unsupported constructs.
The system reports unsupported constructs explicitly.
* **5a.** Source mapping is ambiguous.
The system reports ambiguity and may fall back to merged output.
* **6a.** Import completes with degradations.
The system returns output plus warning classification.
### Related Use Cases
* UC-009 Redistribute imported edits to source files
* UC-010 Fallback to merged Markdown import
* UC-022 Review warning and ambiguity report
---
## UC-007 Round-trip single-file document
**Level:** Summary
**Primary Actor:** Document Author
**Goal:** Complete a full single-file round-trip editing cycle
### Preconditions
* A valid single-file project exists
### Guarantees
**Success**
* A DOCX review artifact is built
* The edited DOCX is imported back
* Semantic drift is reported
**Minimal**
* Canonical source remains recoverable
### Main Success Scenario
1. The actor validates the single-file project.
2. The actor builds a DOCX artifact.
3. A reviewer edits the DOCX.
4. The actor imports the edited DOCX.
5. The actor compares baseline and imported Markdown.
6. The system returns a drift report.
7. The actor decides how to apply imported changes.
### Includes
* UC-003 Validate project readiness
* UC-004 Build DOCX review artifact
* UC-006 Import edited DOCX into Markdown
* UC-011 Detect round-trip drift
### Extensions
* **4a.** Import contains unsupported constructs.
The system provides import output with explicit warnings.
* **5a.** Structural drift is detected.
The system highlights drift classification.
---
## UC-008 Round-trip multi-file document
**Level:** Summary
**Primary Actor:** Technical Editor
**Goal:** Complete a round-trip cycle for a multi-file project while preserving source structure where possible
### Preconditions
* A valid multi-file project exists
* Source mapping or section-origin context is available
### Guarantees
**Success**
* A single review artifact is built from multiple sources
* Imported changes are either redistributed or clearly surfaced in fallback form
* Drift is reported with source-awareness where possible
**Minimal**
* Source structure is not silently lost
### Main Success Scenario
1. The actor inspects the multi-file project.
2. The actor validates the project.
3. The actor builds a single DOCX review artifact.
4. A reviewer edits the DOCX.
5. The actor imports the edited DOCX into the project context.
6. The system attempts source-aware redistribution.
7. The system either redistributes content or provides a managed fallback.
8. The actor runs drift comparison.
9. The system returns redistribution status and drift results.
### Includes
* UC-002 Inspect project configuration
* UC-003 Validate project readiness
* UC-004 Build DOCX review artifact
* UC-006 Import edited DOCX into Markdown
* UC-009 Redistribute imported edits to source files or UC-010 Fallback to merged Markdown import
* UC-011 Detect round-trip drift
### Extensions
* **6a.** Redistribution is ambiguous.
The system falls back to merged output and reports the condition.
* **8a.** Drift affects section boundaries or identifiers.
The system returns structural warnings.
---
## UC-009 Redistribute imported edits to source files
**Level:** User-goal
**Primary Actor:** Technical Editor
**Supporting Actors:** Source Mapping Context
**Goal:** Place imported content back into source-aligned Markdown outputs
### Preconditions
* A project-aware import result exists
* Source-origin metadata or equivalent mapping context exists
### Guarantees
**Success**
* Imported content is redistributed into source-aligned outputs
* Redistribution status is reported
**Minimal**
* The system does not silently assign ambiguous content to incorrect sources
### Main Success Scenario
1. The actor requests source-aware redistribution of imported content.
2. The system loads source-origin mapping information.
3. The system associates imported sections with original source boundaries.
4. The system produces source-aligned Markdown outputs.
5. The system reports redistribution success and any warnings.
### Extensions
* **2a.** Required mapping information is missing.
The system reports redistribution cannot proceed safely.
* **3a.** An imported section matches multiple possible source boundaries.
The system flags the ambiguity.
* **4a.** Redistribution is only partially successful.
The system produces partial output and explicit warnings.
### Related Use Cases
* UC-010 Fallback to merged Markdown import
---
## UC-010 Fallback to merged Markdown import
**Level:** User-goal
**Primary Actor:** Technical Editor
**Goal:** Recover a usable Markdown result when source redistribution cannot be completed safely
### Preconditions
* An import result exists
* Safe redistribution is unavailable or ambiguous
### Guarantees
**Success**
* A merged Markdown output is available
* The fallback condition is explicitly disclosed
**Minimal**
* Imported content is not lost
### Main Success Scenario
1. The system detects that source redistribution cannot be completed safely.
2. The system prepares a merged Markdown representation.
3. The system marks the result as fallback output.
4. The actor receives the merged Markdown and mapping warnings.
### Extensions
* **2a.** Import output itself is degraded.
The system returns fallback output with additional warning classification.
---
## UC-011 Detect round-trip drift
**Level:** User-goal
**Primary Actor:** Technical Editor
**Goal:** Compare original and imported document states and classify their differences
### Preconditions
* A baseline document state and an imported or alternate state exist
### Guarantees
**Success**
* The actor receives a drift report
* Differences are classified into meaningful categories
* Structural changes are distinguished from cosmetic normalization
**Minimal**
* No compared content is modified
### Main Success Scenario
1. The actor requests drift comparison.
2. The system loads the baseline and comparison states.
3. The system compares the two states.
4. The system classifies detected differences.
5. The system reports comparison status and classified differences.
### Extensions
* **2a.** One of the compared states is unavailable.
The system reports comparison cannot proceed.
* **4a.** Broken references or citation issues are detected.
The system classifies them as structural or unresolved problems.
### Related Use Cases
* UC-022 Review warning and ambiguity report
---
## UC-012 List available families
**Level:** User-goal
**Primary Actor:** Template Administrator
**Goal:** Discover built-in and registered families
### Preconditions
* The system is operational
### Guarantees
**Success**
* The actor receives a list of available families
* Built-in and registered families are visible with metadata
**Minimal**
* Registry state remains unchanged
### Main Success Scenario
1. The actor requests the family list.
2. The system retrieves available family registrations.
3. The system returns family identifiers and metadata summary.
### Extensions
* **2a.** Registry information is unavailable.
The system reports inability to provide the list.
---
## UC-013 Register additional template family
**Level:** User-goal
**Primary Actor:** Template Administrator
**Supporting Actors:** Template Registry
**Goal:** Add a new template/style family to the system
### Preconditions
* The actor has a candidate family definition and associated resources
### Guarantees
**Success**
* The system accepts and registers the new family
* The family becomes discoverable for future use
**Minimal**
* Invalid registrations are not partially accepted without disclosure
### Main Success Scenario
1. The actor submits a new family registration.
2. The system validates the family definition and referenced resources.
3. The system checks compatibility declarations.
4. The system stores or activates the registration.
5. The system confirms successful registration.
### Extensions
* **2a.** The family definition is invalid.
The system rejects the registration with reasons.
* **3a.** Declared capabilities are inconsistent.
The system reports a validation error.
* **4a.** The family conflicts with an existing identifier.
The system reports a registration conflict.
---
## UC-014 Build LEVEL1 document
**Level:** User-goal
**Primary Actor:** Document Author
**Goal:** Process a document using LEVEL1 features
### Preconditions
* The project declares LEVEL1 or compatible capability
* The selected family supports LEVEL1
### Guarantees
**Success**
* The document is processed with support for headings, lists, tables, footnotes, images, and links
**Minimal**
* Unsupported non-LEVEL1 constructs are surfaced rather than silently accepted
### Main Success Scenario
1. The actor requests build or round-trip processing for a LEVEL1 project.
2. The system recognizes the declared feature level.
3. The system applies LEVEL1 support rules.
4. The system returns the resulting artifacts and/or reports.
### Extensions
* **2a.** The selected family does not support LEVEL1.
The system reports incompatibility.
* **3a.** Unsupported constructs are encountered.
The system reports warnings or failures as appropriate.
---
## UC-015 Build LEVEL3 document
**Level:** User-goal
**Primary Actor:** Technical Editor
**Goal:** Process a document using LEVEL3 features
### Preconditions
* The project declares LEVEL3
* The selected family supports LEVEL3-related behaviors
* Supporting processors are available where needed
### Guarantees
**Success**
* The document is processed with support for cross references, numbered figures, diagrams, and bibliography-aware workflows
**Minimal**
* Unsupported advanced features are surfaced explicitly
### Main Success Scenario
1. The actor requests build or round-trip processing for a LEVEL3 project.
2. The system recognizes the declared feature level.
3. The system resolves required supporting processors.
4. The system applies LEVEL3 support rules.
5. The system returns artifacts and reports.
### Includes
* UC-016 Generate automatic diagrams
* UC-017 Process bibliography-aware document
### Extensions
* **3a.** Required supporting processors are unavailable.
The system reports inability to complete full LEVEL3 processing.
* **4a.** Cross references or citations cannot be resolved safely.
The system reports unresolved advanced constructs.
---
## UC-016 Generate automatic diagrams
**Level:** Subfunction
**Primary Actor:** Document Author
**Supporting Actors:** Diagram Renderer
**Goal:** Include rendered diagrams derived from source declarations
### Preconditions
* The project includes diagram source declarations
* Diagram rendering capability is available
### Guarantees
**Success**
* Diagram output is included in generated artifacts
* Diagram intent remains linked to its source representation within the managed workflow
**Minimal**
* Missing diagram support is explicitly reported
### Main Success Scenario
1. The system encounters a diagram source declaration during processing.
2. The system invokes diagram-capable processing.
3. The system includes the resulting rendered diagram in build output.
4. The system preserves the association between diagram source intent and rendered content.
### Extensions
* **2a.** The renderer is unavailable or fails.
The system reports the diagram processing problem.
---
## UC-017 Process bibliography-aware document
**Level:** Subfunction
**Primary Actor:** Technical Editor
**Supporting Actors:** Bibliography Processor
**Goal:** Process citations and bibliography in supported workflows
### Preconditions
* The project contains citation-bearing content or bibliography declarations
### Guarantees
**Success**
* Citations and bibliography are included in supported output forms
* Round-trip ambiguities are surfaced when preservation cannot be guaranteed
**Minimal**
* Bibliography-related failures are explicitly reported
### Main Success Scenario
1. The system encounters citation-bearing content.
2. The system resolves bibliography-related inputs.
3. The system applies bibliography-aware processing.
4. The system includes citations and bibliography in generated output.
5. The system reports unresolved or ambiguous citation conditions when present.
### Extensions
* **2a.** Bibliography data is missing or unresolved.
The system reports bibliography-related issues.
* **3a.** Citation preservation cannot be guaranteed during import.
The system reports ambiguity.
---
## UC-018 Execute local CLI workflow
**Level:** Summary
**Primary Actor:** Build Operator
**Goal:** Use markidocx locally through the command-line interface
### Preconditions
* A local markidocx CLI is available
* Relevant project or artifact inputs are accessible
### Guarantees
**Success**
* The actor can invoke core system functions locally
* The system returns human-readable and optionally structured outputs
**Minimal**
* Failed local operations produce explicit status information
### Main Success Scenario
1. The actor invokes a CLI command.
2. The system interprets the requested operation.
3. The system performs the underlying function.
4. The system returns status, outputs, warnings, and errors as applicable.
### Variations
* Validate project
* Build artifact
* Import DOCX
* Compare drift
* Inspect project
* List families
* Register family
* Run tests
---
## UC-019 Execute REST-based workflow
**Level:** Summary
**Primary Actor:** Integration Client
**Goal:** Use markidocx through the REST interface
### Preconditions
* The service is operational
* The client can submit project or artifact data
### Guarantees
**Success**
* The client can invoke core system functions through REST
* The service returns structured machine-consumable results
**Minimal**
* Unsuccessful operations return explicit structured errors
### Main Success Scenario
1. The client submits a request to the service.
2. The system interprets the request.
3. The system performs the requested function.
4. The system returns a structured response with status and outputs.
### Variations
* Validate project
* Build artifact
* Import DOCX
* Compare drift
* List families
* Register family
* Retrieve capability metadata
* Retrieve health and version status
---
## UC-020 Execute MCP-based workflow
**Level:** Summary
**Primary Actor:** MCP Client
**Goal:** Use markidocx through MCP-discoverable tools and resources
### Preconditions
* An MCP-capable client is connected to the system
* The markidocx MCP interface is operational
### Guarantees
**Success**
* The client can discover and invoke markidocx tools
* The client can retrieve project, capability, and result information
**Minimal**
* Unsupported tool requests are explicitly rejected or reported
### Main Success Scenario
1. The client discovers available markidocx tools and resources.
2. The client chooses a tool or resource.
3. The system performs the requested operation.
4. The system returns a structured tool result or resource content.
### Variations
* List templates/styles
* Inspect project
* Validate project
* Build DOCX
* Import DOCX
* Compare drift
* Run end-to-end tests
* Retrieve version metadata
---
## UC-021 Run end-to-end regression on stable docs
**Level:** User-goal
**Primary Actor:** Release Manager
**Goal:** Validate the latest stable markidocx documentation corpus as canonical end-to-end testcase
### Preconditions
* The latest stable documentation corpus exists as a managed markidocx project
### Guarantees
**Success**
* The documentation corpus is processed through the required round-trip path
* The resulting validation evidence is available for release decisions
**Minimal**
* Failures are explicitly reported with usable evidence
### Main Success Scenario
1. The actor requests end-to-end regression execution.
2. The system loads the stable documentation corpus.
3. The system validates the documentation project.
4. The system builds required output artifacts.
5. The system performs import and comparison flows as defined by the regression profile.
6. The system records and reports regression outcomes.
### Extensions
* **3a.** The documentation project is no longer valid.
The system reports regression cannot proceed successfully.
* **5a.** Drift exceeds acceptable thresholds.
The system marks regression with warnings or failure.
### Related Use Cases
* UC-025 Build and inspect release evidence
---
## UC-022 Review warning and ambiguity report
**Level:** User-goal
**Primary Actor:** Technical Editor
**Goal:** Inspect unsupported, degraded, or ambiguous processing outcomes
### Preconditions
* A prior operation produced warnings or ambiguity results
### Guarantees
**Success**
* The actor receives a structured explanation of detected issues
* The actor can distinguish unsupported from degraded but usable outcomes
**Minimal**
* The original operation result remains available
### Main Success Scenario
1. The actor opens or requests an operation report.
2. The system presents warnings, ambiguities, and severity classification.
3. The actor inspects the reported issues.
4. The actor uses the report to decide next steps.
---
## UC-023 Retrieve system capability metadata
**Level:** User-goal
**Primary Actor:** Integration Client
**Goal:** Discover what the system supports before invoking deeper operations
### Preconditions
* The system is operational
### Guarantees
**Success**
* The actor receives capability metadata about supported feature levels, families, and interfaces
**Minimal**
* System state remains unchanged
### Main Success Scenario
1. The actor requests capability metadata.
2. The system gathers capability information.
3. The system returns a structured capability description.
---
## UC-024 Retrieve health and version status
**Level:** User-goal
**Primary Actor:** Build Operator
**Goal:** Determine whether the system is available and what version is running
### Preconditions
* The system or service endpoint is reachable
### Guarantees
**Success**
* The actor receives health and version information
**Minimal**
* System state remains unchanged
### Main Success Scenario
1. The actor requests health or version information.
2. The system returns machine-consumable status information.
---
## UC-025 Build and inspect release evidence
**Level:** User-goal
**Primary Actor:** Release Manager
**Goal:** Produce auditable evidence of release-time round-trip behavior
### Preconditions
* A regression flow has been executed or is about to be executed
### Guarantees
**Success**
* Build, import, validation, and drift evidence is assembled and inspectable
* Release decisions can reference the generated evidence
**Minimal**
* Missing evidence is explicitly reported
### Main Success Scenario
1. The actor requests release evidence generation or review.
2. The system collects relevant validation, build, import, and drift outputs.
3. The system assembles them into a coherent evidence set.
4. The actor reviews the evidence for release decision-making.
---
# 8. Use Case Grouping by Functional Domain
## 8.1 Project Lifecycle
* UC-001 Define document project
* UC-002 Inspect project configuration
* UC-003 Validate project readiness
## 8.2 Build and Template Workflow
* UC-004 Build DOCX review artifact
* UC-005 Build using alternate family
* UC-012 List available families
* UC-013 Register additional template family
## 8.3 Round-Trip Workflow
* UC-006 Import edited DOCX into Markdown
* UC-007 Round-trip single-file document
* UC-008 Round-trip multi-file document
* UC-009 Redistribute imported edits to source files
* UC-010 Fallback to merged Markdown import
* UC-011 Detect round-trip drift
* UC-022 Review warning and ambiguity report
## 8.4 Feature-Level Workflow
* UC-014 Build LEVEL1 document
* UC-015 Build LEVEL3 document
* UC-016 Generate automatic diagrams
* UC-017 Process bibliography-aware document
## 8.5 Interface Workflow
* UC-018 Execute local CLI workflow
* UC-019 Execute REST-based workflow
* UC-020 Execute MCP-based workflow
* UC-023 Retrieve system capability metadata
* UC-024 Retrieve health and version status
## 8.6 Release and Governance Workflow
* UC-021 Run end-to-end regression on stable docs
* UC-025 Build and inspect release evidence
---
# 9. Lifecycle Metadata Guidance
Each use case in the managed catalog should support the following governance metadata:
* **Status:** draft, active, deprecated, retired
* **Owner:** responsible role or team
* **Version introduced**
* **Last review date**
* **Trace links:** PRD sections, FRS IDs, test suites
* **Change note**
Suggested default metadata model:
```yaml
use_case:
id: UC-004
name: Build DOCX review artifact
status: active
owner: product-management
version_introduced: "1.0"
last_review: "2026-03-14"
traces:
prd:
- "Section 6 Product Use Cases"
- "Section 8 Success Criteria"
frs:
- "FR-201"
- "FR-203"
- "FR-204"
- "FR-208"
tests:
- "E2E-BUILD-001"
- "CLI-BUILD-001"
- "REST-BUILD-001"
```
---
# 10. Suggested Traceability Anchors to FRS
## Project and Manifest
* UC-001 ↔ FR-101 to FR-106
* UC-002 ↔ FR-104 to FR-105
* UC-003 ↔ FR-701 to FR-703
## Build and Export
* UC-004 ↔ FR-201 to FR-209
* UC-005 ↔ FR-204 to FR-205, FR-603 to FR-610
## Import and Round-Trip
* UC-006 ↔ FR-301 to FR-308
* UC-007 ↔ FR-201 to FR-308, FR-704 to FR-710
* UC-008 ↔ FR-401 to FR-407, FR-704 to FR-710
* UC-009 ↔ FR-404 to FR-407
* UC-010 ↔ FR-406
* UC ↔ FR-704 to FR-710
* UC-022 ↔ FR-1202 to FR-1205
## Feature Levels
* UC-014 ↔ FR-501 to FR-506
* UC-015 ↔ FR-531 to FR-537
* UC-016 ↔ FR-533 to FR-534
* UC-017 ↔ FR-535 to FR-536
## Interfaces
* UC-018 ↔ FR-801 to FR-812
* UC-019 ↔ FR-901 to FR-912
* UC-020 ↔ FR-1001 to FR-1011
* UC-023 ↔ FR-909, FR-1011
* UC-024 ↔ FR-910 to FR-911
## Release and Testing
* UC-021 ↔ FR-1101 to FR-1106
* UC-025 ↔ FR-1106, FR-701 to FR-710
---
# 11. Optional Machine-Readable UCC Example
```yse:
id: UC-008
name: Round-trip multi-file document
scope: markidocx
level: summary
primary_actor: Technical Editor
supporting_actors:
- Source Mapping Context
preconditions:
- A valid multi-file project exists
- Source mapping or section-origin context is available
guarantees:
success:
- A single review artifact is built from multiple sources
- Imported changes are either redistributed or clearly surfaced in fallback form
- Drift is reported with source-awareness where possible
minimal:
- Source structure is not silently lost
main_success_scenario:
- Actor inspects the multi-file project
- Actor validates the project
- Actor builds a single DOCX review artifact
- Reviewer edits the DOCX
- Actor imports the edited DOCX into the project context
- System attempts source-aware redistribution
- System either redistributes content or provides a managed fallback
- Actor runs drift comparison
- System returns redistribution status and drift results
extensions:
- step: 6
condition: redistribution is ambiguous
outcome: system falls back to merged output and reports the condition
- step: 8
condition: drift affects section boundaries or identifiers
outcome: system returns structural warnings
includes:
- UC-002
- UC-003
- UC-004
- UC-006
- UC-011
status: draft
owner: product-management
last_review: 2026-03-14
```
---
# 12. Concise Summary
This UCC gives markidocx a proper **actor-goal-centered functional backbone**. It expands the earlier use cases into a governed catalog that can now serve as the bridge between:
* PRD intent
* FRS requirement groups
* acceptance test design
* later API and schema contracts
The strongest next step is to derive either:
1. an **acceptance criteria catalog** from these use cases, or
2. a **machine-readable UCC schema pack** with one YAML file per use case plus an index manifest.
xxx
Reference in New Issue View Git Blame Copy Permalink