generated from coulomb/repo-seed
89 lines
7.2 KiB
Markdown
89 lines
7.2 KiB
Markdown
# Practical Usecase Relevance
|
|
|
|
This document translates the project intent, PRD, FRS, and current
|
|
implementation into practical adoption usecases for `markitect-tool`.
|
|
|
|
The relevance expectations are based on the local product scope plus a light web
|
|
research pass across Markdown documentation ecosystems, docs-as-code practice,
|
|
RAG/agent context tooling, policy-as-code systems, and Markdown publishing
|
|
systems.
|
|
|
|
## Research Signals
|
|
|
|
- CommonMark exists because Markdown needed a strongly defined, compatible
|
|
specification across many implementations: https://commonmark.org/
|
|
- GitLab documents large handbook and product-doc workflows in Markdown, with
|
|
linting/style enforcement in the pipeline:
|
|
https://handbook.gitlab.com/docs/markdown-guide/ and
|
|
https://docs.gitlab.com/development/documentation/styleguide/
|
|
- MkDocs positions itself directly as project documentation with Markdown and
|
|
uses Markdown files plus YAML configuration:
|
|
https://www.mkdocs.org/
|
|
- Docusaurus uses Markdown/MDX as its main authoring format and highlights the
|
|
tension between CommonMark compatibility and richer MDX component behavior:
|
|
https://docusaurus.io/docs/3.2.1/markdown-features
|
|
- LangChain and Semantic Kernel both model RAG around loading, splitting,
|
|
storing, retrieving, and injecting text context:
|
|
https://docs.langchain.com/oss/python/langchain/rag and
|
|
https://learn.microsoft.com/en-us/semantic-kernel/frameworks/agent/agent-rag
|
|
- OPA and OpenFGA show that policy and authorization are commonly externalized
|
|
into dedicated engines, which supports Markitect's adapter-first boundary:
|
|
https://www.openpolicyagent.org/docs and https://openfga.dev/docs/fga
|
|
- Quarkdown demonstrates current interest in Markdown extended with functions,
|
|
scripting, and richer publishing semantics:
|
|
https://www.quarkdown.net/about
|
|
- Click already supports shell completion for Bash, Zsh, and Fish when exposed
|
|
through an installed entry point:
|
|
https://click.palletsprojects.com/en/stable/shell-completion/
|
|
- pdoc and Sphinx show common expectations for automatic Python API
|
|
documentation from public APIs and docstrings:
|
|
https://pdoc.dev/ and
|
|
https://www.sphinx-doc.org/en/master/usage/extensions/apidoc.html
|
|
|
|
## Usecase Matrix
|
|
|
|
| Usecase | Relevance | Why It Matters | Current Support | E2E Variations |
|
|
| --- | --- | --- | --- | --- |
|
|
| Parse Markdown into structured ASTs | Foundational | Every higher-level workflow needs stable structure and source spans. | `mkt parse`, `mkt ast`, API parser primitives | Small single note, typical ADR/PRD, large multi-section document |
|
|
| Contract-check business documents | High | Teams need predictable structure, assertions, field validation, and diagnostics. | `mkt contract validate/check/form-state`, contract APIs | Small concept note, typical ADR/business letter, large PRD/FRS bundle |
|
|
| Query and extract reusable content | High | Docs-as-code and agent/RAG workflows need selectors over source Markdown. | `mkt query`, `mkt extract`, JSONPath, indexed query | Small file query, typical docs directory, large cached corpus |
|
|
| Transform, compose, include, transclude | High | Real document pipelines need deterministic reuse without manual copy/paste. | `mkt transform`, `compose`, `include`, references, processors | Small include, typical multi-source review, large composed handbook segment |
|
|
| Generate documents from templates/contracts | High | Practical adoption depends on producing useful Markdown, not only checking it. | `mkt template`, `mkt generate`, document functions | Small template, typical release notes, large generated document pack |
|
|
| Declarative Markdown workflows | High | Business usecases need repeatable pipelines with intent, inputs, outputs, and diagnostics. | `mkt workflow inspect/plan/run` | Small source-snippet workflow, typical ADR release notes, large multi-input pipeline |
|
|
| Local indexing, search, and incremental refresh | High | Large corpora require speed, change detection, and retrieval without reparsing everything. | `mkt cache`, `mkt backend refresh-plan`, `mkt search` | Small two-file index, typical docs tree, large synthetic corpus |
|
|
| Policy-aware knowledge access | Medium-high | Enterprise use needs safe filtering and explainable denial without making Markitect the IAM system. | `mkt policy`, policy-filtered `search`, policy-filtered `cache query` | Public/private notes, typical trust-zone docs, large labelled corpus |
|
|
| Literate weave/tangle workflows | Medium-high | Knuth-style authoring and modern docs-as-code both benefit from code/document roundtrips. | `mkt tangle`, `mkt weave` | Small code chunk, typical app skeleton, large multi-file tangle |
|
|
| Explode/implode document sections | Medium-high | Human editing and review often need splitting documents while preserving roundtrip integrity. | `mkt explode`, `mkt implode` | Small flat split, typical hierarchical doc, large section tree |
|
|
| Runtime forms and dynamic context prefill | Medium-high | Structured documents often originate as form-like workflows with validation and prefills. | `mkt contract form-state`, runtime context APIs | Small static form, typical prefilled letter, large dynamic contract |
|
|
| Agent working-memory context packages | Medium-high | Agents need bounded, inspectable context payloads with provenance and policy rechecks. | `mkt context pack/activate/explain/refresh/list` | Small source package, typical indexed package, large budget-limited package |
|
|
| Document function layer | Medium | Quarkdown-like function layers make Markdown more expressive while keeping deterministic boundaries. | `mkt function list/check/render` | Small inline function, typical function fence, large generated function document |
|
|
| Internal extension framework | Medium | Future growth requires extension isolation, descriptors, docs, safety, and CLI/API visibility. | `mkt extension list/inspect/commands`, extension APIs | Built-in registry, docs descriptor, future optional adapter descriptor |
|
|
| Generated CLI/API documentation | Medium | Accessibility improves when users can discover the live surface without reading code. | `mkt docs cli`, `mkt docs api`, generated docs files | Console output, committed Markdown, packaging docs build |
|
|
|
|
## Coverage Expectations
|
|
|
|
The adoption polish work should treat these usecases as the public contract:
|
|
|
|
- Each usecase should have at least one API test and one CLI test.
|
|
- Each high-relevance usecase should have small, typical, and large E2E
|
|
fixtures.
|
|
- Large fixtures should be synthetic enough to stay fast but big enough to catch
|
|
obvious performance regressions.
|
|
- E2E tests should assert useful behavior, diagnostics, and output shape, not
|
|
only zero exit codes.
|
|
- Optional adapters should be tested through stable local fakes and must not
|
|
require network or live LLM calls.
|
|
|
|
## Accessibility Expectations
|
|
|
|
Markitect becomes more accessible when:
|
|
|
|
- users can install one command and get `--help`, tab completion, and generated
|
|
command docs
|
|
- every architecture capability is discoverable through `mkt extension`
|
|
- API docs are generated from the public API and kept close to the source
|
|
- examples map directly to usecases and can be copied into local experiments
|
|
- diagnostics use stable codes, source locations, and concise remediation hints
|
|
- defaults support practical single-file work before asking users to configure a
|
|
full project
|