UAT: SkillRegistryService docstrings reference non-existent exception classes DuplicateSkillError and SkillNotFoundError #3731

New issue

Open

opened 2026-04-05 22:20:45 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 22:20:45 +00:00

Owner

Metadata

Branch: fix/v3.6.0/skill-registry-docstring-exceptions
Commit Message: fix(skill-registry): correct docstrings to reference actual exception types
Milestone: Backlog (see note below)
Parent Epic: #3374

SkillRegistryService in src/cleveragents/application/services/skill_registry_service.py has docstrings that reference exception classes DuplicateSkillError and SkillNotFoundError that do not exist anywhere in the codebase. This violates the spec's static typing requirements and misleads callers about the error contract.

What Was Tested

Code-level analysis of src/cleveragents/application/services/skill_registry_service.py.

Expected Behavior (from spec)

All docstrings must accurately describe the exceptions raised. The spec requires static typing compliance and accurate documentation.

Actual Behavior

add_skill() docstring:

def add_skill(self, skill: Skill) -> Skill:
    """Register a new skill.
    ...
    Raises:
        DuplicateSkillError: If the name already exists.  ← Does not exist!
        DatabaseError: On persistence failure.             ← Does not exist!
    """
    return self._skill_repo.create(skill)

update_skill() docstring:

def update_skill(self, skill: Skill) -> Skill:
    """Update an existing skill definition.
    ...
    Raises:
        SkillNotFoundError: If the skill is not found.  ← Does not exist!
        DatabaseError: On persistence failure.           ← Does not exist!
    """
    return self._skill_repo.update(skill)

Neither DuplicateSkillError, SkillNotFoundError, nor DatabaseError exist in the codebase. The actual exceptions raised by the repository layer are different (likely SkillExecutionError with SkillErrorType.SKILL_NOT_FOUND or SkillErrorType.VALIDATION_ERROR).

Impact

Callers cannot write correct except clauses based on the documented API
Static type checkers cannot verify exception handling
Violates the spec's documentation accuracy requirements

Code Location

src/cleveragents/application/services/skill_registry_service.py — add_skill() and update_skill() docstrings

Subtasks

Determine actual exceptions raised by SkillRepository.create() and SkillRepository.update()
Update add_skill() docstring to reference correct exception types
Update update_skill() docstring to reference correct exception types
Add Behave tests verifying the correct exceptions are raised
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

All subtasks above are completed and checked off
All docstrings reference only exception classes that exist in the codebase
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done
nox -e typecheck passes
nox -e unit_tests passes
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/v3.6.0/skill-registry-docstring-exceptions` - **Commit Message**: `fix(skill-registry): correct docstrings to reference actual exception types` - **Milestone**: Backlog (see note below) - **Parent Epic**: #3374 `SkillRegistryService` in `src/cleveragents/application/services/skill_registry_service.py` has docstrings that reference exception classes `DuplicateSkillError` and `SkillNotFoundError` that do not exist anywhere in the codebase. This violates the spec's static typing requirements and misleads callers about the error contract. ## What Was Tested Code-level analysis of `src/cleveragents/application/services/skill_registry_service.py`. ## Expected Behavior (from spec) All docstrings must accurately describe the exceptions raised. The spec requires static typing compliance and accurate documentation. ## Actual Behavior **`add_skill()` docstring**: ```python def add_skill(self, skill: Skill) -> Skill: """Register a new skill. ... Raises: DuplicateSkillError: If the name already exists. ← Does not exist! DatabaseError: On persistence failure. ← Does not exist! """ return self._skill_repo.create(skill) ``` **`update_skill()` docstring**: ```python def update_skill(self, skill: Skill) -> Skill: """Update an existing skill definition. ... Raises: SkillNotFoundError: If the skill is not found. ← Does not exist! DatabaseError: On persistence failure. ← Does not exist! """ return self._skill_repo.update(skill) ``` Neither `DuplicateSkillError`, `SkillNotFoundError`, nor `DatabaseError` exist in the codebase. The actual exceptions raised by the repository layer are different (likely `SkillExecutionError` with `SkillErrorType.SKILL_NOT_FOUND` or `SkillErrorType.VALIDATION_ERROR`). ## Impact - Callers cannot write correct `except` clauses based on the documented API - Static type checkers cannot verify exception handling - Violates the spec's documentation accuracy requirements ## Code Location `src/cleveragents/application/services/skill_registry_service.py` — `add_skill()` and `update_skill()` docstrings ## Subtasks - [ ] Determine actual exceptions raised by `SkillRepository.create()` and `SkillRepository.update()` - [ ] Update `add_skill()` docstring to reference correct exception types - [ ] Update `update_skill()` docstring to reference correct exception types - [ ] Add Behave tests verifying the correct exceptions are raised - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done - [ ] All subtasks above are completed and checked off - [ ] All docstrings reference only exception classes that exist in the codebase - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done - [ ] `nox -e typecheck` passes - [ ] `nox -e unit_tests` passes - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 22:20:58 +00:00

#3374 Epic: E2E Workflow Specification Tests & Code Review Tool Examples

freemo referenced this issue

2026-04-05 22:22:14 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo referenced this issue

2026-04-05 22:22:42 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo referenced this issue

2026-04-05 22:25:59 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654