Skip to content

docs: add specification for the error catalogue in the SDK #1266

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ogenstad wants to merge 1 commit into
base: infrahub-develop
Choose a base branch
from
+420 −0
Draft

docs: add specification for the error catalogue in the SDK #1266

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions dev/specs/ifc-3034-error-catalogue/checklists/requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Specification Quality Checklist: Error Catalogue in the Python SDK

**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: 2026-08-21
**Feature**: [spec.md](../spec.md)

## Content Quality

- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed

## Requirement Completeness

- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Success criteria are technology-agnostic (no implementation details)
- [x] All acceptance scenarios are defined
- [x] Edge cases are identified
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified

## Feature Readiness

- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows
- [x] Feature meets measurable outcomes defined in Success Criteria
- [x] No implementation details leak into specification

## Notes

Two checklist items were resolved by scoping rather than by rewriting, and the reasoning is recorded
here so the plan phase does not relitigate it:

- **"No implementation details" / "written for non-technical stakeholders"** — for a library, the
exception hierarchy *is* the user-facing product, so class names, catalogue codes, and the
transport split are domain vocabulary rather than implementation leakage. The spec names those and
deliberately withholds module layout, file names, generator implementation, and test mechanics.
Recorded as an explicit assumption in the spec rather than left implicit.
- **"Success criteria are technology-agnostic"** — SC-001 through SC-008 are stated as outcomes a
consumer or reviewer can verify (a failure is handleable without reading a message; no string
matching remains; a stale artefact fails validation) rather than as internal mechanics. They do
reference exceptions and catalogue codes, which is unavoidable and correct for this feature.

Items deferred to the plan by design, not omission:

- The reconciliation of the `identifier` attribute on the unified `NodeNotFoundError`, where the
client-side and catalogue meanings differ in type. FR-016 requires the unification; the spec records
the conflict as an edge case and leaves the mechanism to the plan.
- The rule for which error in a multi-error response selects the raised class. FR-013 requires the

@cubic-dev-ai cubic-dev-ai Bot Aug 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The multi-error response contract is still unresolved. Specify a deterministic precedence rule for selecting the raised class while retaining the complete error list.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At dev/specs/ifc-3034-error-catalogue/checklists/requirements.md, line 52:

<comment>The multi-error response contract is still unresolved. Specify a deterministic precedence rule for selecting the raised class while retaining the complete error list.</comment>

<file context>
@@ -0,0 +1,53 @@
+- The reconciliation of the `identifier` attribute on the unified `NodeNotFoundError`, where the
+  client-side and catalogue meanings differ in type. FR-016 requires the unification; the spec records
+  the conflict as an edge case and leaves the mechanism to the plan.
+- The rule for which error in a multi-error response selects the raised class. FR-013 requires the
+  rule to be explicit and documented; it does not pick one.
</file context>

rule to be explicit and documented; it does not pick one.
Loading