From 13e478bcafe4a4cef618606e1a99d0d7ecec27c8 Mon Sep 17 00:00:00 2001 From: Maximus2012 Date: Fri, 13 Mar 2026 18:47:18 +0600 Subject: [PATCH 01/16] feat: extract intervals_chain, intervals_tuple, intervals_distribution from intervals.py (#83 #84 #85) --- src/foapy/__init__.py | 8 ++ src/foapy/core/__init__.py | 6 +- src/foapy/core/_intervals.py | 38 +-------- src/foapy/core/_intervals_chain.py | 99 +++++++++++++++++++++++ src/foapy/core/_intervals_distribution.py | 80 ++++++++++++++++++ src/foapy/core/_intervals_tuple.py | 75 +++++++++++++++++ 6 files changed, 271 insertions(+), 35 deletions(-) create mode 100644 src/foapy/core/_intervals_chain.py create mode 100644 src/foapy/core/_intervals_distribution.py create mode 100644 src/foapy/core/_intervals_tuple.py diff --git a/src/foapy/__init__.py b/src/foapy/__init__.py index 7747f277..dad48c9b 100644 --- a/src/foapy/__init__.py +++ b/src/foapy/__init__.py @@ -29,6 +29,9 @@ from foapy.core import alphabet # noqa: F401 from foapy.core import binding # noqa: F401 from foapy.core import intervals # noqa: F401 + from foapy.core import intervals_chain # noqa: F401 + from foapy.core import intervals_distribution # noqa: F401 + from foapy.core import intervals_tuple # noqa: F401 from foapy.core import mode # noqa: F401 from foapy.core import order # noqa: F401 @@ -41,6 +44,8 @@ __all__ = list( __foapy_submodules__ | {"order", "intervals", "alphabet", "binding", "mode"} + | {"intervals_chain", "intervals_tuple"} + | {"intervals_distribution"} | {"__version__", "__array_namespace_info__"} ) @@ -74,6 +79,9 @@ def __dir__(): "exceptions" "ma", "order", "intervals", + "intervals_chain", + "intervals_tuple", + "intervals_distribution", "alphabet", "binding", "mode", diff --git a/src/foapy/core/__init__.py b/src/foapy/core/__init__.py index 693700fb..ce85d271 100644 --- a/src/foapy/core/__init__.py +++ b/src/foapy/core/__init__.py @@ -14,12 +14,16 @@ from ._alphabet import alphabet # noqa: F401 from ._binding import binding # noqa: F401 from ._mode import mode # noqa: F401 + from ._intervals_chain import intervals_chain # noqa: F401 + from ._intervals_tuple import intervals_tuple # noqa: F401 + from ._intervals_distribution import intervals_distribution # noqa: F401 from ._intervals import intervals # noqa: F401 from ._order import order # noqa: F401 # isort: on - __all__ = list({"binding", "mode", "intervals", "order", "alphabet"}) + __all__ = list({"binding", "mode", "intervals", "order", "alphabet", + "intervals_chain", "intervals_tuple", "intervals_distribution"}) def __dir__(): return __all__ diff --git a/src/foapy/core/_intervals.py b/src/foapy/core/_intervals.py index 158838ae..208fbfaf 100644 --- a/src/foapy/core/_intervals.py +++ b/src/foapy/core/_intervals.py @@ -2,6 +2,7 @@ from numpy import ndarray from foapy.core import binding as constants_binding +from foapy.core import intervals_chain, intervals_tuple from foapy.core import mode as constants_mode @@ -135,40 +136,9 @@ def intervals(X, binding: int, mode: int) -> ndarray: if binding == constants_binding.end: ar = ar[::-1] - perm = ar.argsort(kind="mergesort") - - mask_shape = ar.shape - mask = np.empty(mask_shape[0] + 1, dtype=bool) - mask[:1] = True - mask[1:-1] = ar[perm[1:]] != ar[perm[:-1]] - mask[-1:] = True # or mask[-1] = True - - first_mask = mask[:-1] - last_mask = mask[1:] - - intervals = np.empty(ar.shape, dtype=np.intp) - intervals[1:] = perm[1:] - perm[:-1] - - delta = len(ar) - perm[last_mask] if mode == constants_mode.cycle else 1 - intervals[first_mask] = perm[first_mask] + delta - - inverse_perm = np.empty(ar.shape, dtype=np.intp) - inverse_perm[perm] = np.arange(ar.shape[0]) - - if mode == constants_mode.lossy: - intervals[first_mask] = 0 - intervals = intervals[inverse_perm] - result = intervals[intervals != 0] - elif mode == constants_mode.normal: - result = intervals[inverse_perm] - elif mode == constants_mode.cycle: - result = intervals[inverse_perm] - elif mode == constants_mode.redundant: - result = intervals[inverse_perm] - redundant_intervals = len(ar) - perm[last_mask] - if binding == constants_binding.end: - redundant_intervals = redundant_intervals[::-1] - result = np.concatenate((result, redundant_intervals)) + result = intervals_chain(ar, mode) + result = intervals_tuple(ar, result, mode, binding) + if binding == constants_binding.end: result = result[::-1] diff --git a/src/foapy/core/_intervals_chain.py b/src/foapy/core/_intervals_chain.py new file mode 100644 index 00000000..b6914184 --- /dev/null +++ b/src/foapy/core/_intervals_chain.py @@ -0,0 +1,99 @@ +import numpy as np +from numpy import ndarray + +from foapy.core import mode as constants_mode + + +def intervals_chain(ar: ndarray, mode: int) -> ndarray: + """ + Build an intervals chain from a 1-D array. + + An intervals chain is an n-tuple of natural numbers representing the distance + between equal elements in a sequence. This function encapsulates the core + chain-building logic: given a 1-D array [ar] (already oriented for the chosen + binding direction) and a [mode], it computes the raw intervals array before + any binding-specific reversal is applied. + + The function supports four behavioural strategies at sequence boundaries: + + * **normal / bounded** ([mode.normal]) – the leading boundary interval + (distance from the virtual start to the first occurrence) is included; + the trailing boundary interval is not added. + * **cyclic** ([mode.cycle]) – the leading and trailing boundary intervals + are summed into a single interval placed at the position of the first + occurrence, as if the sequence were circular. + * **lossy** ([mode.lossy]) – boundary (first-occurrence) intervals are set + to [0] so the caller can filter them out. + * **redundant** ([mode.redundant]) – same as [mode.normal] for the chain itself; + the caller is responsible for appending the trailing boundary intervals. + + Parameters + ---------- + ar : ndarray + 1-D array whose intervals chain is to be built. For [binding.end] + the caller must reverse [ar] **before** passing it here, and reverse + the result afterwards. + mode : int + One of [mode.lossy], [mode.normal], [mode.cycle], + [mode.redundant]. Controls how boundary intervals are handled. + + Returns + ------- + chain : ndarray + Raw intervals array of the same length as [ar], in the original + element order. For [mode.lossy] the boundary zeros are still + present; filtering is left to the caller. + + Notes + ----- + This function is the low-level building block used by + [foapy.intervals]. It does not validate [mode] or the shape + of [ar] – validation is the responsibility of the caller. + + Examples + -------- + Build a bounded (normal) intervals chain: + + >>> import numpy as np + >>> from foapy.core import intervals_chain + >>> from foapy.core import mode + >>> ar = np.asarray(['b', 'a', 'b', 'c', 'b']) + >>> intervals_chain(ar, mode.normal) + array([1, 2, 2, 4, 2]) + + Build a cyclic intervals chain (leading boundary becomes wrap-around sum): + + >>> intervals_chain(ar, mode.cycle) + array([1, 5, 2, 5, 2]) + + For lossy mode the first-occurrence intervals are zeroed out so the + caller can filter them with [result][result != 0]: + + >>> intervals_chain(ar, mode.lossy) + array([0, 0, 2, 0, 2]) + """ + + perm = ar.argsort(kind="mergesort") + + mask = np.empty(ar.shape[0] + 1, dtype=bool) + mask[:1] = True + mask[1:-1] = ar[perm[1:]] != ar[perm[:-1]] + mask[-1:] = True # or mask[-1:] = True + + first_mask = mask[:-1] + last_mask = mask[1:] + + chain = np.empty(ar.shape, dtype=np.intp) + chain[1:] = perm[1:] - perm[:-1] + + delta = len(ar) - perm[last_mask] if mode == constants_mode.cycle else 1 + chain[first_mask] = perm[first_mask] + delta + + if mode == constants_mode.lossy: + chain[first_mask] = 0 + + inverse_perm = np.empty(ar.shape, dtype=np.intp) + inverse_perm[perm] = np.arange(ar.shape[0]) + chain = chain[inverse_perm] + + return chain diff --git a/src/foapy/core/_intervals_distribution.py b/src/foapy/core/_intervals_distribution.py new file mode 100644 index 00000000..45f18bb6 --- /dev/null +++ b/src/foapy/core/_intervals_distribution.py @@ -0,0 +1,80 @@ +import numpy as np +from numpy import ndarray + +from foapy.core import intervals_tuple as _intervals_tuple # noqa: F401 + + +def intervals_distribution(tuple_result: ndarray) -> ndarray: + """ + Calculate intervals distribution from an intervals tuple. + + An intervals distribution is an n-tuple of natural numbers where the + index represents the interval length and the value is the count of + its appearances in the intervals tuple. + + Caller is responsible for preparing the tuple_result correctly: + - For mode.lossy: boundary intervals already removed by intervals_tuple + - For mode.redundant: trailing intervals already appended by intervals_tuple + - For mode.normal, mode.cycle: pass tuple_result as-is + + Parameters + ---------- + tuple_result : ndarray + Intervals tuple produced by intervals_tuple. + + Returns + ------- + result : ndarray + Array of length max(tuple_result) where result[i] is the count + of interval value i+1 in the tuple. + + Examples + -------- + >>> import numpy as np + >>> from foapy import binding, mode + >>> from foapy.core import intervals_chain + >>> from foapy.core import intervals_tuple + >>> from foapy.core import intervals_distribution + >>> ar = np.asarray([2, 4, 2, 2, 4]) + + From documentation example - chain [1, 2, 3, 2, 4, 6]: + + >>> intervals_distribution(np.array([1, 2, 3, 2, 4, 6])) + array([1, 2, 1, 1, 0, 1]) + + Normal mode: + + >>> chain = intervals_chain(ar, mode.normal) + >>> tpl = intervals_tuple(ar, chain, mode.normal, binding.start) + >>> intervals_distribution(tpl) + array([2, 2, 1]) + + Lossy mode — boundary intervals already removed: + + >>> chain = intervals_chain(ar, mode.lossy) + >>> tpl = intervals_tuple(ar, chain, mode.lossy, binding.start) + >>> intervals_distribution(tpl) + array([1, 1, 1]) + + Redundant mode — trailing intervals already appended: + + >>> chain = intervals_chain(ar, mode.redundant) + >>> tpl = intervals_tuple(ar, chain, mode.redundant, binding.start) + >>> intervals_distribution(tpl) + array([2, 3, 1]) + + Empty tuple: + + >>> intervals_distribution(np.array([])) + array([]) + """ + + if len(tuple_result) == 0: + return np.array([], dtype=np.intp) + + max_interval = int(tuple_result.max()) + distribution = np.zeros(max_interval, dtype=np.intp) + for interval in tuple_result: + distribution[int(interval) - 1] += 1 + + return distribution diff --git a/src/foapy/core/_intervals_tuple.py b/src/foapy/core/_intervals_tuple.py new file mode 100644 index 00000000..f0e27249 --- /dev/null +++ b/src/foapy/core/_intervals_tuple.py @@ -0,0 +1,75 @@ +import numpy as np +from numpy import ndarray + +from foapy.core import binding as constants_binding +from foapy.core import mode as constants_mode + + +def intervals_tuple(ar: ndarray, chain: ndarray, mode: int, binding: int) -> ndarray: + """ + Convert an intervals chain into a final intervals tuple. + + Applies unchaining strategies to the raw intervals chain produced by + [intervals_chain], handling boundary intervals according to the given mode. + + Parameters + ---------- + ar : ndarray + 1-D array (already oriented for binding direction) used to compute + trailing boundary intervals for [mode.redundant]. + chain : ndarray + Raw intervals chain produced by [intervals_chain]. + mode : int + One of [mode.lossy], [mode.normal], [mode.cycle], [mode.redundant]. + binding : int + One of [binding.start], [binding.end]. Used to correctly order + trailing boundary intervals for [mode.redundant]. + + Returns + ------- + result : ndarray + Final intervals tuple. + + Examples + -------- + >>> import numpy as np + >>> from foapy.core import mode, binding + >>> from foapy.core import intervals_chain + >>> from foapy.core import intervals_tuple + >>> ar = np.asarray(['b', 'a', 'b', 'c', 'b']) + + Normal mode — chain is returned as-is: + + >>> chain = intervals_chain(ar, mode.normal) + >>> intervals_tuple(ar, chain, mode.normal) + array([1, 2, 2, 4, 2]) + + Lossy mode — boundary (zero) intervals are removed: + + >>> chain = intervals_chain(ar, mode.lossy) + >>> intervals_tuple(ar, chain, mode.lossy) + array([2, 2]) + + Redundant mode — trailing boundary intervals are appended: + + >>> chain = intervals_chain(ar, mode.redundant) + >>> intervals_tuple(ar, chain, mode.redundant) + array([1, 2, 2, 4, 2, 4, 1, 2]) + """ + + if mode == constants_mode.lossy: + return chain[chain != 0] + + if mode == constants_mode.redundant: + perm = ar.argsort(kind="mergesort") + mask = np.empty(ar.shape[0] + 1, dtype=bool) + mask[:1] = True + mask[1:-1] = ar[perm[1:]] != ar[perm[:-1]] + mask[-1:] = True + last_mask = mask[1:] + trailing = len(ar) - perm[last_mask] + if binding == constants_binding.end: + trailing = trailing[::-1] + return np.concatenate((chain, trailing)) + + return chain From 3b26e12ef2c621e4836c4b294e250d922eb6b268 Mon Sep 17 00:00:00 2001 From: Maximus2012 Date: Fri, 13 Mar 2026 19:02:46 +0600 Subject: [PATCH 02/16] style: reformat __init__.py --- src/foapy/core/__init__.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/foapy/core/__init__.py b/src/foapy/core/__init__.py index ce85d271..44ead92d 100644 --- a/src/foapy/core/__init__.py +++ b/src/foapy/core/__init__.py @@ -22,8 +22,18 @@ # isort: on - __all__ = list({"binding", "mode", "intervals", "order", "alphabet", - "intervals_chain", "intervals_tuple", "intervals_distribution"}) + __all__ = list( + { + "binding", + "mode", + "intervals", + "order", + "alphabet", + "intervals_chain", + "intervals_tuple", + "intervals_distribution", + } + ) def __dir__(): return __all__ From 9b593369b3749b44636f6dbebeec71693d8ea33c Mon Sep 17 00:00:00 2001 From: Igor Rodionov Date: Sat, 28 Mar 2026 18:54:36 +0100 Subject: [PATCH 03/16] Added CLAUDE --- .gitignore | 3 ++ CLAUDE.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index d93c807f..38c7be7e 100644 --- a/.gitignore +++ b/.gitignore @@ -64,3 +64,6 @@ foapy.iws .idea *.ipr .idea/ + +# Claude settings +.claude/settings.local.json diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..78fd1338 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,80 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +FoaPy is a Python library for **Formal Order Analysis (FOA)** — analysis of symbolic sequences by mapping them to their structural order and extracting intervals between repeated symbols. Core dependency: `numpy >= 1.20`. + +## Commands + +**Run all tests:** +```bash +tox -e default +``` + +**Run a single test file or test:** +```bash +tox -e default -- tests/test_characteristics/test_volume.py -v +tox -e default -- tests/test_characteristics/test_volume.py::TestVolume::test_dataset_1 -v +``` + +**Run tests matching a keyword:** +```bash +tox -e default -- -k order -q +``` + +**Lint (black, isort, flake8):** +```bash +pipx run pre-commit run --all-files --show-diff-on-failure +``` + +**Build distribution:** +```bash +tox -e clean,build +``` + +**Build and serve docs:** +```bash +tox -e docs +tox -e docsserve +``` + +## Architecture + +### Core Pipeline (`src/foapy/core/`) + +The FOA pipeline works in stages: + +1. **`order(X)`** — maps a sequence to integer indices (positions in first-appearance alphabet) and optionally returns the `alphabet` +2. **`intervals(X, binding, mode)`** — extracts intervals (distances between consecutive occurrences of the same symbol) from an ordered sequence + +`intervals()` is built from two lower-level primitives: +- **`intervals_chain`** — computes raw interval chains before boundary handling +- **`intervals_tuple`** — applies boundary strategy to produce the final result + +### Binding and Mode enums + +These two enums control how `intervals()` handles sequence boundaries: + +- **`binding`**: `start` (left-to-right) or `end` (right-to-left) +- **`mode`**: `lossy` (drop boundary intervals), `normal` (one boundary), `cycle` (cyclic wrap), `redundant` (both boundaries) + +### Characteristics (`src/foapy/characteristics/`) + +Each characteristic is a standalone module (e.g., `volume`, `arithmetic_mean`, `depth`, `regularity`) that takes an intervals array and returns a scalar. They share no base class — each is a thin function over numpy operations. + +### Masked-Array Support (`src/foapy/ma/`) + +`foapy.ma` mirrors the core API for sequences with missing data (numpy masked arrays): `ma.order()`, `ma.alphabet()`, `ma.intervals()`. The `characteristics/ma/` subdirectory provides masked-array variants of each characteristic. + +### Exceptions (`src/foapy/exceptions/`) + +- `Not1DArrayException` — raised when input is not 1-D +- `InconsistentOrderException` — raised when order/alphabet pair is incompatible + +## Test Conventions + +Tests are in `tests/`. Characteristics tests share a base class `CharacteristicsTest` (in `tests/test_characteristics/characterisitcs_test.py`) providing `AssertCase()` and `AssertBatch()` helpers. `AssertBatch` verifies results across all `binding × mode` combinations using a nested dict of expected values. + +Numerical comparisons use epsilon tolerance — use `AssertCase`/`AssertBatch` rather than plain `assert` for floating-point characteristics. From 4cfeabe0511c5611a77b09adde46a8e8a91ce9a8 Mon Sep 17 00:00:00 2001 From: Igor Rodionov Date: Sat, 28 Mar 2026 19:26:11 +0100 Subject: [PATCH 04/16] Added speckit --- .claude/commands/speckit.analyze.md | 184 ++++ .claude/commands/speckit.checklist.md | 295 ++++++ .claude/commands/speckit.clarify.md | 181 ++++ .claude/commands/speckit.constitution.md | 84 ++ .claude/commands/speckit.implement.md | 198 +++++ .claude/commands/speckit.plan.md | 153 ++++ .claude/commands/speckit.specify.md | 306 +++++++ .claude/commands/speckit.tasks.md | 200 +++++ .claude/commands/speckit.taskstoissues.md | 30 + .specify/init-options.json | 11 + .specify/memory/constitution.md | 158 ++++ .specify/scripts/bash/check-prerequisites.sh | 190 ++++ .specify/scripts/bash/common.sh | 329 +++++++ .specify/scripts/bash/create-new-feature.sh | 335 +++++++ .specify/scripts/bash/setup-plan.sh | 72 ++ .specify/scripts/bash/update-agent-context.sh | 837 ++++++++++++++++++ .specify/templates/agent-file-template.md | 28 + .specify/templates/checklist-template.md | 40 + .specify/templates/constitution-template.md | 50 ++ .specify/templates/plan-template.md | 104 +++ .specify/templates/spec-template.md | 128 +++ .specify/templates/tasks-template.md | 251 ++++++ src/foapy/core/__init__.py | 16 +- src/foapy/core/_intervals.py | 38 +- 24 files changed, 4199 insertions(+), 19 deletions(-) create mode 100644 .claude/commands/speckit.analyze.md create mode 100644 .claude/commands/speckit.checklist.md create mode 100644 .claude/commands/speckit.clarify.md create mode 100644 .claude/commands/speckit.constitution.md create mode 100644 .claude/commands/speckit.implement.md create mode 100644 .claude/commands/speckit.plan.md create mode 100644 .claude/commands/speckit.specify.md create mode 100644 .claude/commands/speckit.tasks.md create mode 100644 .claude/commands/speckit.taskstoissues.md create mode 100644 .specify/init-options.json create mode 100644 .specify/memory/constitution.md create mode 100755 .specify/scripts/bash/check-prerequisites.sh create mode 100755 .specify/scripts/bash/common.sh create mode 100755 .specify/scripts/bash/create-new-feature.sh create mode 100755 .specify/scripts/bash/setup-plan.sh create mode 100755 .specify/scripts/bash/update-agent-context.sh create mode 100644 .specify/templates/agent-file-template.md create mode 100644 .specify/templates/checklist-template.md create mode 100644 .specify/templates/constitution-template.md create mode 100644 .specify/templates/plan-template.md create mode 100644 .specify/templates/spec-template.md create mode 100644 .specify/templates/tasks-template.md diff --git a/.claude/commands/speckit.analyze.md b/.claude/commands/speckit.analyze.md new file mode 100644 index 00000000..0c71cf32 --- /dev/null +++ b/.claude/commands/speckit.analyze.md @@ -0,0 +1,184 @@ +--- +description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal + +Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`. + +## Operating Constraints + +**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). + +**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`. + +## Execution Steps + +### 1. Initialize Analysis Context + +Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: + +- SPEC = FEATURE_DIR/spec.md +- PLAN = FEATURE_DIR/plan.md +- TASKS = FEATURE_DIR/tasks.md + +Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command). +For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +### 2. Load Artifacts (Progressive Disclosure) + +Load only the minimal necessary context from each artifact: + +**From spec.md:** + +- Overview/Context +- Functional Requirements +- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact) +- User Stories +- Edge Cases (if present) + +**From plan.md:** + +- Architecture/stack choices +- Data Model references +- Phases +- Technical constraints + +**From tasks.md:** + +- Task IDs +- Descriptions +- Phase grouping +- Parallel markers [P] +- Referenced file paths + +**From constitution:** + +- Load `.specify/memory/constitution.md` for principle validation + +### 3. Build Semantic Models + +Create internal representations (do not include raw artifacts in output): + +- **Requirements inventory**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → `user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%"). +- **User story/action inventory**: Discrete user actions with acceptance criteria +- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases) +- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements + +### 4. Detection Passes (Token-Efficient Analysis) + +Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary. + +#### A. Duplication Detection + +- Identify near-duplicate requirements +- Mark lower-quality phrasing for consolidation + +#### B. Ambiguity Detection + +- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria +- Flag unresolved placeholders (TODO, TKTK, ???, ``, etc.) + +#### C. Underspecification + +- Requirements with verbs but missing object or measurable outcome +- User stories missing acceptance criteria alignment +- Tasks referencing files or components not defined in spec/plan + +#### D. Constitution Alignment + +- Any requirement or plan element conflicting with a MUST principle +- Missing mandated sections or quality gates from constitution + +#### E. Coverage Gaps + +- Requirements with zero associated tasks +- Tasks with no mapped requirement/story +- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks + +#### F. Inconsistency + +- Terminology drift (same concept named differently across files) +- Data entities referenced in plan but absent in spec (or vice versa) +- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note) +- Conflicting requirements (e.g., one requires Next.js while other specifies Vue) + +### 5. Severity Assignment + +Use this heuristic to prioritize findings: + +- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality +- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion +- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case +- **LOW**: Style/wording improvements, minor redundancy not affecting execution order + +### 6. Produce Compact Analysis Report + +Output a Markdown report (no file writes) with the following structure: + +## Specification Analysis Report + +| ID | Category | Severity | Location(s) | Summary | Recommendation | +|----|----------|----------|-------------|---------|----------------| +| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version | + +(Add one row per finding; generate stable IDs prefixed by category initial.) + +**Coverage Summary Table:** + +| Requirement Key | Has Task? | Task IDs | Notes | +|-----------------|-----------|----------|-------| + +**Constitution Alignment Issues:** (if any) + +**Unmapped Tasks:** (if any) + +**Metrics:** + +- Total Requirements +- Total Tasks +- Coverage % (requirements with >=1 task) +- Ambiguity Count +- Duplication Count +- Critical Issues Count + +### 7. Provide Next Actions + +At end of report, output a concise Next Actions block: + +- If CRITICAL issues exist: Recommend resolving before `/speckit.implement` +- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions +- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'" + +### 8. Offer Remediation + +Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) + +## Operating Principles + +### Context Efficiency + +- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation +- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis +- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow +- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts + +### Analysis Guidelines + +- **NEVER modify files** (this is read-only analysis) +- **NEVER hallucinate missing sections** (if absent, report them accurately) +- **Prioritize constitution violations** (these are always CRITICAL) +- **Use examples over exhaustive rules** (cite specific instances, not generic patterns) +- **Report zero issues gracefully** (emit success report with coverage statistics) + +## Context + +$ARGUMENTS diff --git a/.claude/commands/speckit.checklist.md b/.claude/commands/speckit.checklist.md new file mode 100644 index 00000000..b7624e22 --- /dev/null +++ b/.claude/commands/speckit.checklist.md @@ -0,0 +1,295 @@ +--- +description: Generate a custom checklist for the current feature based on user requirements. +--- + +## Checklist Purpose: "Unit Tests for English" + +**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain. + +**NOT for verification/testing**: + +- ❌ NOT "Verify the button clicks correctly" +- ❌ NOT "Test error handling works" +- ❌ NOT "Confirm the API returns 200" +- ❌ NOT checking if code/implementation matches the spec + +**FOR requirements quality validation**: + +- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness) +- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity) +- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency) +- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage) +- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases) + +**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Execution Steps + +1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list. + - All file paths must be absolute. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST: + - Be generated from the user's phrasing + extracted signals from spec/plan/tasks + - Only ask about information that materially changes checklist content + - Be skipped individually if already unambiguous in `$ARGUMENTS` + - Prefer precision over breadth + + Generation algorithm: + 1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts"). + 2. Cluster signals into candidate focus areas (max 4) ranked by relevance. + 3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit. + 4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria. + 5. Formulate questions chosen from these archetypes: + - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?") + - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?") + - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?") + - Audience framing (e.g., "Will this be used by the author only or peers during PR review?") + - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?") + - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?") + + Question formatting rules: + - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters + - Limit to A–E options maximum; omit table if a free-form answer is clearer + - Never ask the user to restate what they already said + - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope." + + Defaults when interaction impossible: + - Depth: Standard + - Audience: Reviewer (PR) if code-related; Author otherwise + - Focus: Top 2 relevance clusters + + Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more. + +3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers: + - Derive checklist theme (e.g., security, review, deploy, ux) + - Consolidate explicit must-have items mentioned by user + - Map focus selections to category scaffolding + - Infer any missing context from spec/plan/tasks (do NOT hallucinate) + +4. **Load feature context**: Read from FEATURE_DIR: + - spec.md: Feature requirements and scope + - plan.md (if exists): Technical details, dependencies + - tasks.md (if exists): Implementation tasks + + **Context Loading Strategy**: + - Load only necessary portions relevant to active focus areas (avoid full-file dumping) + - Prefer summarizing long sections into concise scenario/requirement bullets + - Use progressive disclosure: add follow-on retrieval only if gaps detected + - If source docs are large, generate interim summary items instead of embedding raw text + +5. **Generate checklist** - Create "Unit Tests for Requirements": + - Create `FEATURE_DIR/checklists/` directory if it doesn't exist + - Generate unique checklist filename: + - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`) + - Format: `[domain].md` + - File handling behavior: + - If file does NOT exist: Create new file and number items starting from CHK001 + - If file exists: Append new items to existing file, continuing from the last CHK ID (e.g., if last item is CHK015, start new items at CHK016) + - Never delete or replace existing checklist content - always preserve and append + + **CORE PRINCIPLE - Test the Requirements, Not the Implementation**: + Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for: + - **Completeness**: Are all necessary requirements present? + - **Clarity**: Are requirements unambiguous and specific? + - **Consistency**: Do requirements align with each other? + - **Measurability**: Can requirements be objectively verified? + - **Coverage**: Are all scenarios/edge cases addressed? + + **Category Structure** - Group items by requirement quality dimensions: + - **Requirement Completeness** (Are all necessary requirements documented?) + - **Requirement Clarity** (Are requirements specific and unambiguous?) + - **Requirement Consistency** (Do requirements align without conflicts?) + - **Acceptance Criteria Quality** (Are success criteria measurable?) + - **Scenario Coverage** (Are all flows/cases addressed?) + - **Edge Case Coverage** (Are boundary conditions defined?) + - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?) + - **Dependencies & Assumptions** (Are they documented and validated?) + - **Ambiguities & Conflicts** (What needs clarification?) + + **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**: + + ❌ **WRONG** (Testing implementation): + - "Verify landing page displays 3 episode cards" + - "Test hover states work on desktop" + - "Confirm logo click navigates home" + + ✅ **CORRECT** (Testing requirements quality): + - "Are the exact number and layout of featured episodes specified?" [Completeness] + - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity] + - "Are hover state requirements consistent across all interactive elements?" [Consistency] + - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage] + - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases] + - "Are loading states defined for asynchronous episode data?" [Completeness] + - "Does the spec define visual hierarchy for competing UI elements?" [Clarity] + + **ITEM STRUCTURE**: + Each item should follow this pattern: + - Question format asking about requirement quality + - Focus on what's WRITTEN (or not written) in the spec/plan + - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.] + - Reference spec section `[Spec §X.Y]` when checking existing requirements + - Use `[Gap]` marker when checking for missing requirements + + **EXAMPLES BY QUALITY DIMENSION**: + + Completeness: + - "Are error handling requirements defined for all API failure modes? [Gap]" + - "Are accessibility requirements specified for all interactive elements? [Completeness]" + - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" + + Clarity: + - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]" + - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]" + - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]" + + Consistency: + - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]" + - "Are card component requirements consistent between landing and detail pages? [Consistency]" + + Coverage: + - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" + - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" + - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" + + Measurability: + - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]" + - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]" + + **Scenario Classification & Coverage** (Requirements Quality Focus): + - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios + - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?" + - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]" + - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]" + + **Traceability Requirements**: + - MINIMUM: ≥80% of items MUST include at least one traceability reference + - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]` + - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]" + + **Surface & Resolve Issues** (Requirements Quality Problems): + Ask questions about the requirements themselves: + - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]" + - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]" + - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]" + - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]" + - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]" + + **Content Consolidation**: + - Soft cap: If raw candidate items > 40, prioritize by risk/impact + - Merge near-duplicates checking the same requirement aspect + - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]" + + **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test: + - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior + - ❌ References to code execution, user actions, system behavior + - ❌ "Displays correctly", "works properly", "functions as expected" + - ❌ "Click", "navigate", "render", "load", "execute" + - ❌ Test cases, test plans, QA procedures + - ❌ Implementation details (frameworks, APIs, algorithms) + + **✅ REQUIRED PATTERNS** - These test requirements quality: + - ✅ "Are [requirement type] defined/specified/documented for [scenario]?" + - ✅ "Is [vague term] quantified/clarified with specific criteria?" + - ✅ "Are requirements consistent between [section A] and [section B]?" + - ✅ "Can [requirement] be objectively measured/verified?" + - ✅ "Are [edge cases/scenarios] addressed in requirements?" + - ✅ "Does the spec define [missing aspect]?" + +6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### ` lines with globally incrementing IDs starting at CHK001. + +7. **Report**: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize: + - Focus areas selected + - Depth level + - Actor/timing + - Any explicit user-specified must-have items incorporated + +**Important**: Each `/speckit.checklist` command invocation uses a short, descriptive checklist filename and either creates a new file or appends to an existing one. This allows: + +- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`) +- Simple, memorable filenames that indicate checklist purpose +- Easy identification and navigation in the `checklists/` folder + +To avoid clutter, use descriptive types and clean up obsolete checklists when done. + +## Example Checklist Types & Sample Items + +**UX Requirements Quality:** `ux.md` + +Sample items (testing the requirements, NOT the implementation): + +- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]" +- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]" +- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]" +- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]" +- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]" +- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]" + +**API Requirements Quality:** `api.md` + +Sample items: + +- "Are error response formats specified for all failure scenarios? [Completeness]" +- "Are rate limiting requirements quantified with specific thresholds? [Clarity]" +- "Are authentication requirements consistent across all endpoints? [Consistency]" +- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]" +- "Is versioning strategy documented in requirements? [Gap]" + +**Performance Requirements Quality:** `performance.md` + +Sample items: + +- "Are performance requirements quantified with specific metrics? [Clarity]" +- "Are performance targets defined for all critical user journeys? [Coverage]" +- "Are performance requirements under different load conditions specified? [Completeness]" +- "Can performance requirements be objectively measured? [Measurability]" +- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]" + +**Security Requirements Quality:** `security.md` + +Sample items: + +- "Are authentication requirements specified for all protected resources? [Coverage]" +- "Are data protection requirements defined for sensitive information? [Completeness]" +- "Is the threat model documented and requirements aligned to it? [Traceability]" +- "Are security requirements consistent with compliance obligations? [Consistency]" +- "Are security failure/breach response requirements defined? [Gap, Exception Flow]" + +## Anti-Examples: What NOT To Do + +**❌ WRONG - These test implementation, not requirements:** + +```markdown +- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001] +- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003] +- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010] +- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005] +``` + +**✅ CORRECT - These test requirements quality:** + +```markdown +- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001] +- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003] +- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010] +- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005] +- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap] +- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001] +``` + +**Key Differences:** + +- Wrong: Tests if the system works correctly +- Correct: Tests if the requirements are written correctly +- Wrong: Verification of behavior +- Correct: Validation of requirement quality +- Wrong: "Does it do X?" +- Correct: "Is X clearly specified?" diff --git a/.claude/commands/speckit.clarify.md b/.claude/commands/speckit.clarify.md new file mode 100644 index 00000000..300b6edb --- /dev/null +++ b/.claude/commands/speckit.clarify.md @@ -0,0 +1,181 @@ +--- +description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec. I am building with... +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Outline + +Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file. + +Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. + +Execution steps: + +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: + - `FEATURE_DIR` + - `FEATURE_SPEC` + - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) + - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked). + + Functional Scope & Behavior: + - Core user goals & success criteria + - Explicit out-of-scope declarations + - User roles / personas differentiation + + Domain & Data Model: + - Entities, attributes, relationships + - Identity & uniqueness rules + - Lifecycle/state transitions + - Data volume / scale assumptions + + Interaction & UX Flow: + - Critical user journeys / sequences + - Error/empty/loading states + - Accessibility or localization notes + + Non-Functional Quality Attributes: + - Performance (latency, throughput targets) + - Scalability (horizontal/vertical, limits) + - Reliability & availability (uptime, recovery expectations) + - Observability (logging, metrics, tracing signals) + - Security & privacy (authN/Z, data protection, threat assumptions) + - Compliance / regulatory constraints (if any) + + Integration & External Dependencies: + - External services/APIs and failure modes + - Data import/export formats + - Protocol/versioning assumptions + + Edge Cases & Failure Handling: + - Negative scenarios + - Rate limiting / throttling + - Conflict resolution (e.g., concurrent edits) + + Constraints & Tradeoffs: + - Technical constraints (language, storage, hosting) + - Explicit tradeoffs or rejected alternatives + + Terminology & Consistency: + - Canonical glossary terms + - Avoided synonyms / deprecated terms + + Completion Signals: + - Acceptance criteria testability + - Measurable Definition of Done style indicators + + Misc / Placeholders: + - TODO markers / unresolved decisions + - Ambiguous adjectives ("robust", "intuitive") lacking quantification + + For each category with Partial or Missing status, add a candidate question opportunity unless: + - Clarification would not materially change implementation or validation strategy + - Information is better deferred to planning phase (note internally) + +3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: + - Maximum of 5 total questions across the whole session. + - Each question must be answerable with EITHER: + - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR + - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words"). + - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. + - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. + - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). + - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests. + - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic. + +4. Sequential questioning loop (interactive): + - Present EXACTLY ONE question at a time. + - For multiple‑choice questions: + - **Analyze all options** and determine the **most suitable option** based on: + - Best practices for the project type + - Common patterns in similar implementations + - Risk reduction (security, performance, maintainability) + - Alignment with any explicit project goals or constraints visible in the spec + - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice). + - Format as: `**Recommended:** Option [X] - ` + - Then render all options as a Markdown table: + + | Option | Description | + |--------|-------------| + | A |