docs(pro-ux): EPIC-PRO-UX-ERRORS + 2 stories (client-side error UX)#774
Open
rafaelscosta wants to merge 1 commit into
Open
docs(pro-ux): EPIC-PRO-UX-ERRORS + 2 stories (client-side error UX)#774rafaelscosta wants to merge 1 commit into
rafaelscosta wants to merge 1 commit into
Conversation
…[Story PRO-UX.1] Materializes EPIC-PRO-UX-ERRORS with 2 stories elaborated to Ready status (21 ACs total, 23 tasks executable, 13 points). Anchor incident: Robert (costa.wanderl@gmail.com, 2026-05-18) — bateu HTTP 403 cru em "npx -y -p @aiox-squads/core@latest aiox install" porque license-server JÁ retornava error.code SEAT_LIMIT_EXCEEDED em envelope estruturado, mas o CLI client ignorava o body da response e mostrava apenas o status HTTP. Aluno gastou ~30min em comandos client-side que não tinham conserto. EPIC scope: aiox-pro-cli bridge layer que consome envelope estendido (produzido por aios-license-server EPIC-PRO-16) e instancia AIOXError via Pro-specific ErrorRegistry estendendo defaultErrorRegistry (reuso da infra de EPIC-AIOX-ERROR-GOVERNANCE, no parallel error system). Stories: - STORY-PRO-UX.1 (8pts, Ready, blocked_by aios-license-server PRO-16.1) — Create .aiox-core/core/errors/pro-error-registry.js com 5 definitions + packages/aiox-pro-cli/src/error-bridge.js com parseEnvelopeToAIOXError e fallback 3-tier (message_pt > registry.userMessage > server message). - STORY-PRO-UX.2 (5pts, Ready, blocked_by PRO-UX.1) — PT-BR strings finais + conditional render por recovery_hint + OS-aware cleanup (PowerShell vs bash detection, fix do bug observado no caso Robert) + snapshot tests. Constraint arquitetural crítica: categorias do license-server (auth/install/ rate/system) MAPEAM para ErrorCategory existente (PERMISSION/NETWORK/ EXTERNAL_EXECUTOR/UNKNOWN) — NAO inventar categorias novas (Object.freeze em .aiox-core/core/errors/constants.js). Decisao Architect 2026-05-18. Code naming: codes Pro-specific NAO usam prefixo AIOX_ (espelham ErrorCodes do aios-license-server). Aceito pelo regex /^[A-Z0-9_]+$/ em ErrorRegistry._normalizeDefinition. Companion: aios-license-server EPIC-PRO-16 (server envelope contract). Architect G1 review APPROVED 2026-05-18. Files added with -f flag (docs/stories/ is gitignored at repo root, but tracked epic dirs follow same convention as epic-error-governance, epic-123, etc — force-added). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rafaelscosta
requested review from
Pedrovaleriolopez and
oalanicolas
as code owners
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughThree documentation files define a Pro CLI error bridge epic: the epic specifies envelope-to-AIOXError mapping, Pro registry contracts, and an anchor incident UX example; PRO-UX.1 defines the bridge implementation and registry acceptance criteria; PRO-UX.2 defines PT-BR strings, error rendering layout, and OS-aware recovery action execution. ChangesPro UX Error Handling Epic & Implementation Stories
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
📊 Coverage ReportCoverage report not available
Generated by PR Automation (Story 6.1) |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (4)
docs/stories/epic-pro-ux-errors/STORY-PRO-UX.2-PT-BR-MAPPING-AND-RECOVERY.md (2)
224-224: ⚡ Quick winConsolidate or differentiate duplicate "Dev Notes" sections.
The document has two "## Dev Notes" headings (lines 156 and 224), creating the same navigation issue as in PRO-UX.1. Consider consolidating the sections or using distinct sub-headings to improve document structure.
🤖 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/stories/epic-pro-ux-errors/STORY-PRO-UX.2-PT-BR-MAPPING-AND-RECOVERY.md` at line 224, The document contains duplicate "## Dev Notes" headings; consolidate them or give each a distinct heading to avoid navigation conflicts—locate both "## Dev Notes" sections (the one at line ~156 and the one at line ~224) and either merge their content into a single "## Dev Notes" section or rename the second to a specific heading like "## Dev Notes — Recovery" or "## Dev Notes (Mapping)" so they are unique and clear in the table of contents.
139-139: ⚡ Quick winClarify AC12 synchronization with Epic file.
AC12 states "EPIC-PRO-UX-ERRORS anchor section atualizada (no
EPIC-PRO-UX-ERRORS.md): substituir 'Pós-EPIC esperado' pelo output FINAL renderizado". However, the Epic file already contains the expected output (lines 117-130 in EPIC-PRO-UX-ERRORS.md). Consider clarifying whether AC12 means:
- Verify Epic output matches implementation, or
- Update Epic only if output format changes during implementation
This prevents confusion about whether the Epic should be modified as part of this story.
🤖 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/stories/epic-pro-ux-errors/STORY-PRO-UX.2-PT-BR-MAPPING-AND-RECOVERY.md` at line 139, AC12 is ambiguous about whether the EPIC-PRO-UX-ERRORS anchor in EPIC-PRO-UX-ERRORS.md should be overwritten or only validated; update the AC12 text in STORY-PRO-UX.2-PT-BR-MAPPING-AND-RECOVERY.md to explicitly state the intended action: either "Verify that the existing EPIC-PRO-UX-ERRORS expected output (lines showing expected output) matches the implementation and do not change the EPIC file" or "Update the EPIC-PRO-UX-ERRORS anchor only when the rendered output format changes during implementation, and include a note to run snapshot tests before committing"; reference AC12 and the EPIC-PRO-UX-ERRORS.md anchor so reviewers know to either validate or update, not both.docs/stories/epic-pro-ux-errors/STORY-PRO-UX.1-CLI-BRIDGE-AND-PRO-REGISTRY.md (1)
248-248: ⚡ Quick winConsolidate or differentiate duplicate "Dev Notes" sections.
The document has two "## Dev Notes" headings (lines 210 and 248). This breaks document navigation and can confuse readers. Consider consolidating into a single section or using distinct sub-headings like "## Dev Notes: Implementation Details" and "## Dev Notes: Architecture Decisions".
🤖 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/stories/epic-pro-ux-errors/STORY-PRO-UX.1-CLI-BRIDGE-AND-PRO-REGISTRY.md` at line 248, The document currently contains two identical top-level headings "## Dev Notes" (one at the earlier block and one at the later block); resolve this by either merging the content under a single "## Dev Notes" heading or renaming the second heading to a distinct subheading (e.g., "## Dev Notes: Implementation Details" or "## Dev Notes: Architecture Decisions") so readers and navigation targets are unambiguous; update any internal links or references that point to the original "## Dev Notes" to match the chosen consolidated or renamed heading.docs/stories/epic-pro-ux-errors/EPIC-PRO-UX-ERRORS.md (1)
57-74: 💤 Low valueConsider adding language specifiers to code blocks.
The fenced code blocks for the architecture diagram and CLI output examples lack language specifiers. Adding
textorconsoleidentifiers would improve syntax highlighting and rendering in documentation viewers.📝 Proposed improvements
Lines 57-74 (architecture diagram):
-``` +```text ┌─────────────────────────────────────────┐Lines 108-112 and 118-130 (CLI outputs):
-``` +```text ✗ Falha na ativação: HTTP 403Also applies to: 108-112, 118-130
🤖 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/stories/epic-pro-ux-errors/EPIC-PRO-UX-ERRORS.md` around lines 57 - 74, The fenced code blocks in EPIC-PRO-UX-ERRORS.md (the architecture diagram block and the CLI output examples) are missing language specifiers; update the opening backtick fences for the diagram and the CLI output blocks (the blocks around the ASCII box diagram and the lines showing "✗ Falha na ativação: HTTP 403" etc.) to include a language token such as text or console (e.g., ```text) so renderers will apply proper formatting and syntax highlighting.
🤖 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.
Nitpick comments:
In `@docs/stories/epic-pro-ux-errors/EPIC-PRO-UX-ERRORS.md`:
- Around line 57-74: The fenced code blocks in EPIC-PRO-UX-ERRORS.md (the
architecture diagram block and the CLI output examples) are missing language
specifiers; update the opening backtick fences for the diagram and the CLI
output blocks (the blocks around the ASCII box diagram and the lines showing "✗
Falha na ativação: HTTP 403" etc.) to include a language token such as text or
console (e.g., ```text) so renderers will apply proper formatting and syntax
highlighting.
In
`@docs/stories/epic-pro-ux-errors/STORY-PRO-UX.1-CLI-BRIDGE-AND-PRO-REGISTRY.md`:
- Line 248: The document currently contains two identical top-level headings "##
Dev Notes" (one at the earlier block and one at the later block); resolve this
by either merging the content under a single "## Dev Notes" heading or renaming
the second heading to a distinct subheading (e.g., "## Dev Notes: Implementation
Details" or "## Dev Notes: Architecture Decisions") so readers and navigation
targets are unambiguous; update any internal links or references that point to
the original "## Dev Notes" to match the chosen consolidated or renamed heading.
In
`@docs/stories/epic-pro-ux-errors/STORY-PRO-UX.2-PT-BR-MAPPING-AND-RECOVERY.md`:
- Line 224: The document contains duplicate "## Dev Notes" headings; consolidate
them or give each a distinct heading to avoid navigation conflicts—locate both
"## Dev Notes" sections (the one at line ~156 and the one at line ~224) and
either merge their content into a single "## Dev Notes" section or rename the
second to a specific heading like "## Dev Notes — Recovery" or "## Dev Notes
(Mapping)" so they are unique and clear in the table of contents.
- Line 139: AC12 is ambiguous about whether the EPIC-PRO-UX-ERRORS anchor in
EPIC-PRO-UX-ERRORS.md should be overwritten or only validated; update the AC12
text in STORY-PRO-UX.2-PT-BR-MAPPING-AND-RECOVERY.md to explicitly state the
intended action: either "Verify that the existing EPIC-PRO-UX-ERRORS expected
output (lines showing expected output) matches the implementation and do not
change the EPIC file" or "Update the EPIC-PRO-UX-ERRORS anchor only when the
rendered output format changes during implementation, and include a note to run
snapshot tests before committing"; reference AC12 and the EPIC-PRO-UX-ERRORS.md
anchor so reviewers know to either validate or update, not both.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 991f0bc7-1db7-4376-9003-6f8618666fd0
📒 Files selected for processing (3)
docs/stories/epic-pro-ux-errors/EPIC-PRO-UX-ERRORS.mddocs/stories/epic-pro-ux-errors/STORY-PRO-UX.1-CLI-BRIDGE-AND-PRO-REGISTRY.mddocs/stories/epic-pro-ux-errors/STORY-PRO-UX.2-PT-BR-MAPPING-AND-RECOVERY.md
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
1 participant
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
Materializes EPIC-PRO-UX-ERRORS (client-side) + 2 stories — the AIOX Pro CLI consumer half of the cross-repo error UX overhaul. Companion of EPIC-PRO-16 (server-side, aios-license-server PR #11).
Docs-only. No code changes.
Anchor incident: student Robert (2026-05-18) saw raw
HTTP 403inaiox install; license-server already returned structurederror.codebut the CLI ignored it. This EPIC specs the bridge layer that consumes the extended envelope.What's included
EPIC-PRO-UX-ERRORS.md— epic (13 pts, 2 stories)STORY-PRO-UX.1— CLI bridge +pro-error-registry.js(extendsdefaultErrorRegistry)STORY-PRO-UX.2— PT-BR mapping + recovery conditional actions + OS-aware cleanupKey constraints (locked by @architect)
ErrorCategory(PERMISSION/NETWORK/EXTERNAL_EXECUTOR) — no new categories inventedAIOXError+ErrorRegistryfrom EPIC-AIOX-ERROR-GOVERNANCE (no parallel system)ErrorCodes(noAIOX_prefix)Status
Both stories
Ready(status). Blocked by aios-license-server PRO-16.1 (schema gate, PR #11). Implementation follows after PR #11 merges.Test plan
Refs
docs/architecture/adr/ADR-ERROR-GOVERNANCE-CONTRACT.md🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation