docs: migrate feature specs to flow-first use-case docs#142
Merged
Conversation
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
|
Important Review skippedToo many files! This PR contains 204 files, which is 54 over the limit of 150. To get a review, narrow the scope: ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (22)
📒 Files selected for processing (204)
You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis PR migrates the documentation architecture from epic-centered ( ChangesEpic-to-Use-Cases Documentation Migration
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
✨ Finishing Touches🧪 Generate unit tests (beta)
|
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
cursor
Bot
changed the title
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 13
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/use-cases/workflow-engine/execution-history.md (1)
59-67:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix inconsistent API implementation status in this use case.
Line 62 shows
API | ✅, but Line 65 says API work is still pending. Please align the status table with the stated gaps.Suggested edit
-> | API | ✅ | +> | API | ⚠️ |As per coding guidelines
docs/use-cases/**/*.md: Update use-case feature file ACs andImplementation statuscallout in same PR as code changes.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/use-cases/workflow-engine/execution-history.md` around lines 59 - 67, Update the "API" status in the execution-history use case to match the described gaps: change the table checkbox at the top to reflect that API work is pending (remove the ✅ for "API" or mark it as ⏳/Pending) and add a short note referencing the outstanding API items (GET /api/executions paging/filters and running-first sort) so it aligns with the paragraph that follows; also ensure the Implementation status callout and the acceptance criteria (ACs) in the same document are updated in this PR to mention that GetExecutionsByWorkflowHandler/GetAllExecutionsHandler currently rely on IExecutionRepository.GetPagedByWorkflowAsync/GetPagedAsync with server-side pagination and that date-range and trigger-type filters remain to be implemented at the API layer.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Line 90: The grep pattern currently used (grep -r "Application:
⚠️\|Infrastructure: ⚠️" docs/use-cases/) won't match status table rows like "|
Application | ⚠️ |"; update the command to search for the table format instead,
for example replace the quoted pattern with a regex that looks for table cells
(e.g. a pattern matching '\| *(Application|Infrastructure) *\| *⚠️ *\|') so the
command finds rows in docs/use-cases/ where Application or Infrastructure have
the warning status.
In `@docs/playbooks/process.md`:
- Line 139: Replace the current guidance that instructs contributors to add a
single `> **Wireframe**` callout with instructions to instead update the `##
Wireframes` table in the use-case file (i.e., remove the `> **Wireframe**`
callout text and replace it with a directive to populate or update the `##
Wireframes` table rows); also add a reminder that ACs and the `Implementation
status` callout in the use-case markdown must be updated in the same PR as the
code changes to match the flow-first format.
In `@docs/use-cases/data-modeling/model-definition.md`:
- Line 53: Broken/brittle relative link to the Import/Export doc in the line
containing "[E04 F07 Import/Export]": remove the unnecessary
"../../E04-workflow-builder/../../" hop and replace it with a direct relative
path from docs/use-cases/data-modeling/model-definition.md to the
workflow-builder doc (use ../workflow-builder/import-export.md so the link
target is docs/use-cases/workflow-builder/import-export.md); update the markdown
link text accordingly and verify the link resolves locally.
In `@docs/use-cases/data-modeling/README.md`:
- Around line 23-24: The table header currently defines two columns ("Use case"
and "Description") but the separator row has three delimiters; update the
separator row to match two columns by using exactly two column separators (e.g.,
"|---|---|") so the header and separator align and remove the extra pipe that
creates the third column.
In `@docs/use-cases/form-builder/form-definition.md`:
- Line 214: The documentation decision to have IsReferencedByWorkflowAsync run a
raw SQL cross-module query against workflow_definitions.steps should be removed
and replaced with a module-bound approach: stop querying workflow_definitions
from the Form Builder module and instead implement either an event-driven
projection/read-model that the Form Builder can query (populate the projection
from workflow events) or a clear API boundary the Form Builder calls to ask "Is
this form referenced?"; update references to IsReferencedByWorkflowAsync and any
mention of workflow_definitions.steps to point to the new projection or API, and
document using the established cross-module communication mechanisms (Kafka
events for projections, RabbitMQ for commands/sagas, or gRPC for sync RPC) as
the recommended patterns.
In `@docs/use-cases/form-builder/README.md`:
- Around line 23-24: The Markdown table header has two columns ("Use case" and
"Description") but the separator row has the wrong number of delimiters; update
the separator row under the header so it has exactly two column separators
(e.g., change the existing separator to "|---|---|" to match the "Use case" and
"Description" header columns).
In `@docs/use-cases/identity-access/README.md`:
- Around line 23-24: The Markdown table header row "| Use case | Description |"
has a trailing pipe but the separator row uses "|---|---|" without the final
pipe, causing a column delimiter mismatch; update the separator to include the
trailing pipe so it reads "|---|---|" -> "|---|---|" (i.e., change the separator
to "|---|---|") ensuring the separator aligns with the two-column header string
"Use case | Description".
In `@docs/use-cases/page-builder/README.md`:
- Around line 25-27: The Markdown table header declares two columns ("Use case"
and "Description") but the separator row in the diff has three cells; update the
separator row under the header to match two columns (i.e., change the current
three-cell separator to a two-cell separator) so the table lines up correctly
with the "Use case | Description" header.
In `@docs/use-cases/platform-foundation/README.md`:
- Around line 23-24: The Markdown table's separator row has three columns while
the header has two, causing a column mismatch; fix the table by changing the
separator row from "|---|---|---|" (or any 3-column variant) to a two-column
separator "|---|---|" so the header row "| Use case | Description |" and the
separator match, ensuring the table renders correctly.
In `@docs/use-cases/README.md`:
- Line 18: The table row contains unescaped pipe characters inside the cell (the
grep command string) which breaks Markdown table parsing; update that cell by
wrapping the entire command in backticks (e.g., surround the grep command shown
with backticks) or by escaping each pipe inside the command as \| so the row
remains a single table cell—target the table row containing the grep command
string `grep -rE "\\| Application \\| ⚠️\\|\\| Infrastructure \\| ⚠️\\|\\| API
\\| ⚠️" docs/use-cases/` and replace it with the backticked (or pipe-escaped)
version.
In `@docs/use-cases/workflow-builder/README.md`:
- Around line 23-24: The markdown table header line "| Use case | Description |"
has two columns but the delimiter row "|---|---|---|" declares three; update the
delimiter to match two columns by changing "|---|---|---|" to "|---|---|" (or
alternatively add a third header cell to the header row) so the number of
pipe-separated columns in the delimiter matches the header; locate and edit the
lines containing the exact strings "| Use case | Description |" and
"|---|---|---|" in README.md.
In `@docs/use-cases/workflow-builder/triggers.md`:
- Around line 1-35: The top-level use-case section "Use Case Group — Trigger
Configuration" is missing the required Implementation status callout; either add
an "Implementation status" callout (e.g., a brief callout block stating Not
started / In progress / Done and a short implementation note) near the
"Acceptance Criteria" or remove this partial scaffold entirely; update the
section under the header "Use Case Group — Trigger Configuration" and ensure the
new callout appears alongside the "Acceptance Criteria" block so the
docs/use-cases update rule is satisfied.
In `@docs/use-cases/workflow-engine/README.md`:
- Around line 23-24: The table delimiter row is one column too many; update the
second line so the delimiter matches the header "Use case | Description" by
replacing the current "|---|---|---|" (or "|---|---|") row with a two-column
delimiter "|---|---|" so the table has exactly two columns.
---
Outside diff comments:
In `@docs/use-cases/workflow-engine/execution-history.md`:
- Around line 59-67: Update the "API" status in the execution-history use case
to match the described gaps: change the table checkbox at the top to reflect
that API work is pending (remove the ✅ for "API" or mark it as ⏳/Pending) and
add a short note referencing the outstanding API items (GET /api/executions
paging/filters and running-first sort) so it aligns with the paragraph that
follows; also ensure the Implementation status callout and the acceptance
criteria (ACs) in the same document are updated in this PR to mention that
GetExecutionsByWorkflowHandler/GetAllExecutionsHandler currently rely on
IExecutionRepository.GetPagedByWorkflowAsync/GetPagedAsync with server-side
pagination and that date-range and trigger-type filters remain to be implemented
at the API layer.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: fe5c13b4-61e0-4886-b46c-0c640691a707
⛔ Files ignored due to path filters (41)
docs/use-cases/data-modeling/diagrams/data-model.svgis excluded by!**/*.svgdocs/use-cases/data-modeling/wireframes/data-classes.svgis excluded by!**/*.svgdocs/use-cases/data-modeling/wireframes/data-models.svgis excluded by!**/*.svgdocs/use-cases/data-modeling/wireframes/records.svgis excluded by!**/*.svgdocs/use-cases/form-builder/diagrams/form-model.svgis excluded by!**/*.svgdocs/use-cases/form-builder/wireframes/form-editor.svgis excluded by!**/*.svgdocs/use-cases/form-builder/wireframes/form-submission.svgis excluded by!**/*.svgdocs/use-cases/form-builder/wireframes/forms.svgis excluded by!**/*.svgdocs/use-cases/identity-access/diagrams/auth-flow.svgis excluded by!**/*.svgdocs/use-cases/identity-access/wireframes/accept-invitation.svgis excluded by!**/*.svgdocs/use-cases/identity-access/wireframes/change-password.svgis excluded by!**/*.svgdocs/use-cases/identity-access/wireframes/forgot-password.svgis excluded by!**/*.svgdocs/use-cases/identity-access/wireframes/login-unverified.svgis excluded by!**/*.svgdocs/use-cases/identity-access/wireframes/login.svgis excluded by!**/*.svgdocs/use-cases/identity-access/wireframes/register.svgis excluded by!**/*.svgdocs/use-cases/identity-access/wireframes/settings-roles.svgis excluded by!**/*.svgdocs/use-cases/identity-access/wireframes/settings-security.svgis excluded by!**/*.svgdocs/use-cases/identity-access/wireframes/settings-users.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/diagrams/tenant-provisioning.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/email-confirmation.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/pricing.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/register-org-states.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/register-org.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/settings-org-access-denied.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/settings-org-delete-modal.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/settings-org-delete-states.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/settings-org-deletion-scheduled.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/settings-org-free-plan.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/settings-org-profile-states.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/settings-org-upload-states.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/settings-org-usage-error.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/settings-org.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/verify-email-rate-limit.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/verify-email.svgis excluded by!**/*.svgdocs/use-cases/platform-foundation/wireframes/workspace-provisioning.svgis excluded by!**/*.svgdocs/use-cases/workflow-builder/diagrams/workflow-model.svgis excluded by!**/*.svgdocs/use-cases/workflow-builder/wireframes/workflow-editor.svgis excluded by!**/*.svgdocs/use-cases/workflow-builder/wireframes/workflows.svgis excluded by!**/*.svgdocs/use-cases/workflow-engine/diagrams/execution-flow.svgis excluded by!**/*.svgdocs/use-cases/workflow-engine/wireframes/execution-detail.svgis excluded by!**/*.svgdocs/use-cases/workflow-engine/wireframes/executions.svgis excluded by!**/*.svg
📒 Files selected for processing (101)
.github/PULL_REQUEST_TEMPLATE.md.github/workflows/build-and-test.ymlCLAUDE.mdCONTRIBUTING.mddocs/ARCHITECTURE.mddocs/PROGRESS.mddocs/README.mddocs/TECH_STACK.mddocs/diagrams/generate-diagrams.mjsdocs/epics/README.mddocs/epics/_template-feature-us.mddocs/playbooks/agent-checklist.mddocs/playbooks/docs-style.mddocs/playbooks/patterns.mddocs/playbooks/process.mddocs/playbooks/wireframes.mddocs/scripts/generate-diagrams.ps1docs/scripts/generate-wireframes.ps1docs/use-cases/README.mddocs/use-cases/data-modeling/README.mddocs/use-cases/data-modeling/data-classes.mddocs/use-cases/data-modeling/data-records.mddocs/use-cases/data-modeling/diagrams/data-model.excalidrawdocs/use-cases/data-modeling/field-types.mddocs/use-cases/data-modeling/model-definition.mddocs/use-cases/data-modeling/wireframes/data-classes.excalidrawdocs/use-cases/data-modeling/wireframes/data-models.excalidrawdocs/use-cases/data-modeling/wireframes/records.excalidrawdocs/use-cases/form-builder/README.mddocs/use-cases/form-builder/diagrams/form-model.excalidrawdocs/use-cases/form-builder/form-definition.mddocs/use-cases/form-builder/form-fields.mddocs/use-cases/form-builder/form-submission.mddocs/use-cases/form-builder/wireframes/form-editor.excalidrawdocs/use-cases/form-builder/wireframes/form-submission.excalidrawdocs/use-cases/form-builder/wireframes/forms.excalidrawdocs/use-cases/form-builder/workflow-integration.mddocs/use-cases/identity-access/README.mddocs/use-cases/identity-access/authentication.mddocs/use-cases/identity-access/diagrams/auth-flow.excalidrawdocs/use-cases/identity-access/localization-and-theming.mddocs/use-cases/identity-access/password-security.mddocs/use-cases/identity-access/permissions.mddocs/use-cases/identity-access/role-management.mddocs/use-cases/identity-access/user-management.mddocs/use-cases/identity-access/wireframes/accept-invitation.excalidrawdocs/use-cases/identity-access/wireframes/change-password.excalidrawdocs/use-cases/identity-access/wireframes/forgot-password.excalidrawdocs/use-cases/identity-access/wireframes/login-unverified.excalidrawdocs/use-cases/identity-access/wireframes/login.excalidrawdocs/use-cases/identity-access/wireframes/register.excalidrawdocs/use-cases/identity-access/wireframes/settings-roles.excalidrawdocs/use-cases/identity-access/wireframes/settings-security.excalidrawdocs/use-cases/identity-access/wireframes/settings-users.excalidrawdocs/use-cases/page-builder/README.mddocs/use-cases/platform-foundation/README.mddocs/use-cases/platform-foundation/diagrams/tenant-provisioning.excalidrawdocs/use-cases/platform-foundation/organization-management.mddocs/use-cases/platform-foundation/subscription-plans.mddocs/use-cases/platform-foundation/tenant-isolation.mddocs/use-cases/platform-foundation/tenant-registration.mddocs/use-cases/platform-foundation/wireframes/email-confirmation.excalidrawdocs/use-cases/platform-foundation/wireframes/pricing.excalidrawdocs/use-cases/platform-foundation/wireframes/register-org-states.excalidrawdocs/use-cases/platform-foundation/wireframes/register-org.excalidrawdocs/use-cases/platform-foundation/wireframes/settings-org-access-denied.excalidrawdocs/use-cases/platform-foundation/wireframes/settings-org-delete-modal.excalidrawdocs/use-cases/platform-foundation/wireframes/settings-org-delete-states.excalidrawdocs/use-cases/platform-foundation/wireframes/settings-org-deletion-scheduled.excalidrawdocs/use-cases/platform-foundation/wireframes/settings-org-free-plan.excalidrawdocs/use-cases/platform-foundation/wireframes/settings-org-profile-states.excalidrawdocs/use-cases/platform-foundation/wireframes/settings-org-upload-states.excalidrawdocs/use-cases/platform-foundation/wireframes/settings-org-usage-error.excalidrawdocs/use-cases/platform-foundation/wireframes/settings-org.excalidrawdocs/use-cases/platform-foundation/wireframes/verify-email-rate-limit.excalidrawdocs/use-cases/platform-foundation/wireframes/verify-email.excalidrawdocs/use-cases/platform-foundation/wireframes/workspace-provisioning.excalidrawdocs/use-cases/workflow-builder/README.mddocs/use-cases/workflow-builder/branching.mddocs/use-cases/workflow-builder/diagrams/workflow-model.excalidrawdocs/use-cases/workflow-builder/import-export.mddocs/use-cases/workflow-builder/parallel-execution.mddocs/use-cases/workflow-builder/step-types.mddocs/use-cases/workflow-builder/triggers.mddocs/use-cases/workflow-builder/visual-canvas.mddocs/use-cases/workflow-builder/wireframes/workflow-editor.excalidrawdocs/use-cases/workflow-builder/wireframes/workflows.excalidrawdocs/use-cases/workflow-builder/workflow-definition.mddocs/use-cases/workflow-engine/README.mddocs/use-cases/workflow-engine/diagrams/execution-flow.excalidrawdocs/use-cases/workflow-engine/error-handling.mddocs/use-cases/workflow-engine/execution-history.mddocs/use-cases/workflow-engine/execution-management.mddocs/use-cases/workflow-engine/manual-retry.mddocs/use-cases/workflow-engine/step-handlers.mddocs/use-cases/workflow-engine/wireframes/execution-detail.excalidrawdocs/use-cases/workflow-engine/wireframes/executions.excalidrawdocs/wireframes/generate-screens.mjsscripts/check-doc-drift.shscripts/check-use-case-docs.pyscripts/normalize-feature-docs.py
💤 Files with no reviewable changes (3)
- docs/epics/README.md
- scripts/normalize-feature-docs.py
- docs/epics/_template-feature-us.md
✅ Files skipped from review due to trivial changes (17)
- .github/workflows/build-and-test.yml
- docs/use-cases/identity-access/localization-and-theming.md
- docs/ARCHITECTURE.md
- docs/PROGRESS.md
- docs/TECH_STACK.md
- docs/playbooks/patterns.md
- docs/use-cases/data-modeling/field-types.md
- docs/use-cases/workflow-builder/branching.md
- docs/use-cases/workflow-builder/parallel-execution.md
- docs/use-cases/identity-access/user-management.md
- docs/playbooks/wireframes.md
- docs/use-cases/workflow-builder/step-types.md
- docs/use-cases/workflow-builder/import-export.md
- .github/PULL_REQUEST_TEMPLATE.md
- docs/use-cases/workflow-builder/workflow-definition.md
- docs/use-cases/data-modeling/data-records.md
- docs/use-cases/data-modeling/data-classes.md
| **Workarounds:** if you intentionally ship code that violates a P0/P1 rule (because the proper solution is blocked), record it in [`docs/WORKAROUNDS.md`](docs/WORKAROUNDS.md) **in the same PR** with a cleanup trigger. Add a `// WORKAROUND: see docs/WORKAROUNDS.md#<slug>` comment at the violation site. The drift script and the architecture fitness tests (`tests/Architecture/Axis.Architecture.Tests`) enforce both ends. | ||
|
|
||
| **Work priority:** (1) gaps/bugs/failing tests (2) finish current layer (3) next layer in order. Before API work: `grep -r "Application: ⚠️\|Infrastructure: ⚠️" docs/epics/` — resolve or document deferrals ([process.md § 4.5](docs/playbooks/process.md)). | ||
| **Work priority:** (1) gaps/bugs/failing tests (2) finish current layer (3) next layer in order. Before API work: `grep -r "Application: ⚠️\|Infrastructure: ⚠️" docs/use-cases/` — resolve or document deferrals ([process.md § 4.5](docs/playbooks/process.md)). |
There was a problem hiding this comment.
Use-case gap-sweep grep pattern is mismatched to the actual status table format.
At Line 90, the pattern searches Application: ⚠️ / Infrastructure: ⚠️, but status is recorded in table rows (for example | Application | ⚠️ |). This command will often return no hits.
Suggested fix
-**Work priority:** (1) gaps/bugs/failing tests (2) finish current layer (3) next layer in order. Before API work: `grep -r "Application: ⚠️\|Infrastructure: ⚠️" docs/use-cases/` — resolve or document deferrals ([process.md § 4.5](docs/playbooks/process.md)).
+**Work priority:** (1) gaps/bugs/failing tests (2) finish current layer (3) next layer in order. Before API work: `grep -rE "\| Application \| ⚠️\|\| Infrastructure \| ⚠️" docs/use-cases/` — resolve or document deferrals ([process.md § 4.5](docs/playbooks/process.md)).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` at line 90, The grep pattern currently used (grep -r "Application:
⚠️\|Infrastructure: ⚠️" docs/use-cases/) won't match status table rows like "|
Application | ⚠️ |"; update the command to search for the table format instead,
for example replace the quoted pattern with a regex that looks for table cells
(e.g. a pattern matching '\| *(Application|Infrastructure) *\| *⚠️ *\|') so the
command finds rows in docs/use-cases/ where Application or Infrastructure have
the warning status.
| | 1 | Domain **Open work** in `docs/use-cases/{domain}/README.md` | Prioritized gaps (backend vs frontend) | | ||
| | 2 | `docs/use-cases/{domain}/*.md` | Per-use-case ACs + `> **Implementation status**` + `Gaps vs spec` / `**Deferred:**` | | ||
| | 3 | `docs/PROGRESS.md` | Module layer summary; cross-cutting foundation phases | | ||
| | 4 | `grep -rE "\\| Application \\| ⚠️\\|\\| Infrastructure \\| ⚠️\\|\\| API \\| ⚠️" docs/use-cases/` | Use cases with partial backend layers ([agent-checklist](../playbooks/agent-checklist.md)) | |
There was a problem hiding this comment.
Fix broken table row parsing in the grep command example.
The command at Line 18 contains unescaped table separators (|) in a table cell, so Markdown parsers split it into extra columns and truncate content. Wrap the command in backticks (or escape pipes) to keep the row valid.
Suggested fix
-| 4 | `grep -rE "\\| Application \\| ⚠️\\|\\| Infrastructure \\| ⚠️\\|\\| API \\| ⚠️" docs/use-cases/` | Use cases with partial backend layers ([agent-checklist](../playbooks/agent-checklist.md)) |
+| 4 | `grep -rE "\| Application \| ⚠️\|\| Infrastructure \| ⚠️\|\| API \| ⚠️" docs/use-cases/` | Use cases with partial backend layers ([agent-checklist](../playbooks/agent-checklist.md)) |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | 4 | `grep -rE "\\| Application \\| ⚠️\\|\\| Infrastructure \\| ⚠️\\|\\| API \\| ⚠️" docs/use-cases/` | Use cases with partial backend layers ([agent-checklist](../playbooks/agent-checklist.md)) | | |
| | 4 | `grep -rE "\| Application \| ⚠️\|\| Infrastructure \| ⚠️\|\| API \| ⚠️" docs/use-cases/` | Use cases with partial backend layers ([agent-checklist](../playbooks/agent-checklist.md)) | |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 18-18: Table column count
Expected: 3; Actual: 11; Too many cells, extra data will be missing
(MD056, table-column-count)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/use-cases/README.md` at line 18, The table row contains unescaped pipe
characters inside the cell (the grep command string) which breaks Markdown table
parsing; update that cell by wrapping the entire command in backticks (e.g.,
surround the grep command shown with backticks) or by escaping each pipe inside
the command as \| so the row remains a single table cell—target the table row
containing the grep command string `grep -rE "\\| Application \\| ⚠️\\|\\|
Infrastructure \\| ⚠️\\|\\| API \\| ⚠️" docs/use-cases/` and replace it with the
backticked (or pipe-escaped) version.
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Co-authored-by: Phuong Nguyen <phuongnse@users.noreply.github.com>
Review-finding fixes: - Repoint 5 domain READMEs' diagram refs to real per-use-case file paths - Replace self-link ./README.md in Open work tables with actual use-case slugs - docs/README.md: drop missing login.excalidraw, list real wireframes - USE_CASE_TEMPLATE + docs-style: flat asset layout (no ./wireframes/, ./diagrams/) - regenerate-domain-readme-index.py: truncate at word boundary (was 100-char mid-word) - Expand 23 truncated summary rows across 5 domain READMEs from real Purpose - strip-spec-ids: stop stripping legitimate () in code comments - Restore () in 8 source/test comments + drop stale stub comment in HttpStepExecutor - Fill real Purpose/Actor/Trigger/flow for delete-data-class, language, theme - Sweep Gaps vs spec: split Done content out; drop "see gaps below" artifact - check-doc-drift.sh: rename labels from E0N to domain slugs Doc-tree consistency for new agents: - CLAUDE.md + PR template: "feature file" -> "use-case file" (example path too) - patterns.md / process.md / wireframes.md: drop > **Wireframe**: callout, point at ## Wireframes table; refresh ASCII tree to flat layout - Fix agent-checklist broken anchor (use-cases README, not docs README) CI hardening (so the next migration can't slip these past): - New scripts/check-doc-link-targets.py — verifies every `` and `[text](./path)` relative target exists. Closes the broken-image-ref gap that lychee missed in PR #142. Wired into check-doc-drift.sh. - check-use-case-docs.py: flag placeholder Purpose/Actor/Trigger; flag self-link [name](./README.md) in domain READMEs; flag truncated ## Use Cases summary rows; count use cases still on the stock Main flow. - check-doc-drift.sh: stale-terminology guard ("feature file", "see gaps below", > **Wireframe**:, docs/epics/, _template-feature-us). Cleanup: - Delete 6 one-shot migration scripts (no longer needed post-migration) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- check-doc-link-targets.py: strip fenced code blocks and inline backtick spans before scanning for links. Without this, illustrative examples like `[text](./file.md)` inside backticks or markdown code fences trip as "broken link" — exactly what CI flagged on the first push. - agent-checklist.md: rephrase the stale-terminology guard description so the bullet doesn't restate the forbidden phrases in plain text (the bash grep can't distinguish backtick content). The current pattern list lives in scripts/check-doc-drift.sh; the playbook now points there instead. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
phuongnse
added a commit
that referenced
this pull request
May 29, 2026
Comments that cite a specific PR ("landed in PR #142", "ships in PR #97")
go stale as the codebase evolves and duplicate provenance that git history
already owns. Keep the durable rationale, drop the PR pointers. Also widen
the doc-drift-scope CI filter to glob scripts/** instead of enumerating each
checker, so a new checker triggers the job without a manual list edit.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
4 tasks
8 tasks
8 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Migrates product specs from the legacy
docs/epics/E0N-name/features/F0N-*.mdlayout to flow-first use cases: one folder per use case underdocs/use-cases/{domain}/{short-slug}/withREADME.md+ co-located.excalidraw/.svgassets. Strips legacy spec IDs (US-NNN,E0N,F0N) from C# / proto comments.Terminology:
Acceptance Criteria (domain), domain README/open work,PROGRESS.mdheadings by domain slug, dependency links withoutE0NIDs.Structure: keep top-level
docs/diagrams/(platform architecture diagrams) anddocs/wireframes/(shared kit:_template,app-shell). All domain-specific screens + flows live next to their use case (docs/use-cases/{domain}/{slug}/*.excalidraw|.svg).Tooling:
scripts/check-use-case-docs.py(run bycheck-doc-drift.sh) — validates use-case structure + flags template placeholders + counts stub Main-flow files.scripts/regenerate-domain-readme-index.py— regenerates each domain's## Use Casessection with word-boundary summary truncation.scripts/_archive/with a README explaining they should not be re-run.Linked spec
Requirements & rules followed