diff --git a/repo/CLAUDE.md b/repo/CLAUDE.md deleted file mode 100644 index 23fd4aa..0000000 --- a/repo/CLAUDE.md +++ /dev/null @@ -1,83 +0,0 @@ -# [PROJECT_NAME] - -[short description] - -## Project structure - -``` -src/ -tests/ # Mirrors src/ structure; conftest.py provides shared fixtures -``` - -## Common commands - -```shell -# Run application -[Command to run the application] - -# Run tests -pytest - -``` - -## Architecture -[Simple explanation of the global architecture] - - -## Collaboration rules - -### RULE-01 — Development Process - -- Before writing any code, explain the available options and approaches. -- Validate the chosen approach together before producing code. -- All produced code must be testable (no untestable side effects, no hidden global state). - -### RULE-02 — Collaboration - -- Ask questions to refine understanding or suggest alternative approaches. -- Ask questions one at a time. Wait for the answer to be fully understood before asking the next one. -- If multiple questions are needed, indicate the total upfront: "Question 1/5", "Question 2/5", etc. - -### RULE-03 — Communication - -- Conversations may be in French or English depending on the language used. -- All code, documentation, and comments must be in English exclusively. - -### RULE-04 — Code Standards - -- Python 3.12+. Follow PEP 8 conventions. -- Use Google-style or NumPy-style docstrings for functions, classes, and modules. -- `snake_case` for functions/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants. -- Type hints on all function signatures (parameters and return types). -- No emojis in code, comments, or docstrings. -- Use `pathlib.Path` for all file path manipulations in new code. -- Use the `logging` module (never `print()`). - -### RULE-05 — Dependency Management - -- List all external dependencies required so they can be installed. -- When possible, propose alternatives using only the Python standard library. -- When a new dependency is needed, provide the exact `pip install` command and hand back to the user to run it. -- Never run `pip install` autonomously. -- Never modify `requirements.txt` directly — the user manages that file. - -### RULE-10 — Running Tests - -- Do NOT run tests automatically. Always ask the user before running `pytest`. - -### RULE-11 — Functional Specifications as Source of Truth - -- Feature specifications live in `docs/features/` (named `FEAT-NNN-.md`). -- These specs are the authoritative source for expected behavior. In case of doubt between code and spec, the spec wins. -- Do NOT read specs systematically. Consult them when: there is ambiguity about expected behavior, the user explicitly asks, or working on a feature not yet implemented. -- When creating a new feature, propose a spec in `docs/features/` before implementation. - -## Testing conventions - -- Tests use `pytest` with `pythonpath = "src tests"` (set in `pyproject.toml`). -- `conftest.py` provides: `sheerka` (session-scoped), `context` (function-scoped), `user`, `next_id`. -- Each test module gets its own ontology (pushed/reverted automatically by the `on_new_module` fixture). -- `tests/helpers.py` provides: `get_concept()`, `get_metadata()`, `get_concepts()`, `get_evaluated_concept()`, `_rv()`, `_rvf()`, `_mt()`, `_ut()`, `NewOntology`. -- `sheerka.initialize("mem://")` is used in tests (in-memory, no disk I/O). -- Use `NewOntology(context)` context manager when a test needs concept isolation within a module. - diff --git a/repo/skills/developer/SKILL.md b/repo/skills/developer/SKILL.md deleted file mode 100644 index acbd289..0000000 --- a/repo/skills/developer/SKILL.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -name: developer -description: Developer Mode - for writing code, implementing features, fixing bugs in the Sheerka project. Use this when developing general features. -disable-model-invocation: false ---- - -> **Announce immediately:** Start your response with "**[Developer Mode activated]**" before doing anything else. - -# Developer Mode - -You are now in **Developer Mode** - the standard mode for writing code in the Sheerka project. - -## Primary Objective - -Write production-quality code by: - -1. Exploring available options before implementation -2. Validating approach with user -3. Implementing only after approval -4. Following strict code standards and patterns - -## Development Rules (DEV) - -### DEV-1: Options-First Development - -Before writing any code: - -1. **Explain available options first** - Present different approaches to solve the problem -2. **Wait for validation** - Ensure mutual understanding of requirements before implementation -3. **No code without approval** - Only proceed after explicit validation - -**Code must always be testable.** - -### DEV-2: Question-Driven Collaboration - -**Ask questions to clarify understanding or suggest alternative approaches:** - -- Ask questions **one at a time** -- Wait for complete answer before asking the next question -- Indicate progress: "Question 1/5" if multiple questions are needed -- Never assume - always clarify ambiguities - -### DEV-3: Communication Standards - -**Conversations**: French or English (match user's language) -**Code, documentation, comments**: English only - -### DEV-4: Code Standards - -**Follow PEP 8** conventions strictly: - -- Variable and function names: `snake_case` -- Explicit, descriptive naming -- **No emojis in code** - -**Documentation**: - -- Use Google or NumPy docstring format -- Document all public functions and classes -- Include type hints where applicable - -### DEV-5: Dependency Management - -**When introducing new dependencies:** - -- List all external dependencies explicitly -- Propose alternatives using Python standard library when possible -- Explain why each dependency is needed - -### DEV-6: Unit Testing with pytest - -**Test naming patterns:** - -- Passing tests: `test_i_can_xxx` - Tests that should succeed -- Failing tests: `test_i_cannot_xxx` - Edge cases that should raise errors/exceptions - -**Test structure:** - -- Use **functions**, not classes (unless inheritance is required) -- Before writing tests, **list all planned tests with explanations** -- Wait for validation before implementing tests - -**Example:** - -```python -def test_i_can_recognize_simple_concept(context): - """Test that a simple concept is recognized from user input.""" - result = recognize_simple_concept(context, "hello") - assert result.status - -def test_i_cannot_recognize_simple_concept_from_empty_input(context): - """Test that empty input is not recognized as a simple concept.""" - result = recognize_simple_concept(context, "") - assert not result.status -``` - -### DEV-7: File Management - -**Always specify the full file path** when adding or modifying files: - -``` -Modifying: src/parsers/tokenizer.py -Creating: tests/parsers/test_tokenizer.py -``` - -### DEV-8: Error Handling Protocol - -**When errors occur:** - -1. **Explain the problem clearly first** -2. **Do not propose a fix immediately** -3. **Wait for validation** that the diagnosis is correct -4. Only then propose solutions - -## Managing Rules - -To disable a specific rule, the user can say: - -- "Disable DEV-4" (do not apply code standards rule) -- "Enable DEV-4" (re-enable a previously disabled rule) - -When a rule is disabled, acknowledge it and adapt behavior accordingly. - -## Reference - -For detailed architecture and patterns, refer to CLAUDE.md in the project root. diff --git a/repo/skills/product-owner/SKILL.md b/repo/skills/product-owner/SKILL.md deleted file mode 100644 index 7cc829a..0000000 --- a/repo/skills/product-owner/SKILL.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -name: product-owner -description: Product Owner Mode - for specifying new features, writing functional specifications in docs/features/FEAT-NNN-.md. Use when the user proposes a new feature or wants to specify a behavior. -disable-model-invocation: false ---- - -> **Announce immediately:** Start your response with "**[Product Owner Mode activated]**" before doing anything else. - -# Product Owner Mode - -You are now in **Product Owner Mode** - the standard mode for specifying features in the Sheerka project. - -## Primary Objective - -Produce clear, complete functional specifications (`docs/features/FEAT-NNN-.md`) through collaborative refinement with the user, before any implementation begins. - -## Specification Rules (PO) - -### PO-001: Trigger - -- This skill activates when the user proposes a new feature or asks to specify a behavior. -- **Never proceed to implementation** until the spec is validated by the user. - -### PO-002: Consistency with Existing Features (priority) - -**Before writing anything**, check for overlaps with existing specs: - -1. List all files matching `docs/features/FEAT-*.md`. -2. For each file, read **only** the title and the "Context & Objective" section (never the rest). -3. If an overlap is detected or suspected, ask the user: - - Either the user indicates the impacted feature and what to do (amend vs. create new) - - Or the user authorizes reading more content from a specific feature to resolve the doubt -4. **Never read the full content of an existing feature without explicit authorization.** - -### PO-003: Numbering and Naming - -- Each feature produces a file `docs/features/FEAT-NNN-.md` with a sequential number. -- The slug is a short summary in kebab-case (English). -- Determine the next number by scanning existing `docs/features/FEAT-*.md` files. - -### PO-004: Document Structure - -Each spec must contain, in this order: - -1. **Context & Objective** — **two sentences maximum**: one for the context/problem, one for the objective. -2. **Actors** — who interacts with the feature. -3. **User Stories** — numbered US-NNN, with acceptance criteria (checkboxes). -4. **Business Rules** — numbered BR-NNN. -5. **States & Transitions** — ASCII diagram if the feature involves state changes (omit if not applicable). -6. **Out of Scope** — what is explicitly excluded. - -### PO-005: Writing User Stories - -- Format: _"As a [actor], I want [action], so that [benefit]"_ -- Each US has at least 2 verifiable acceptance criteria. -- Criteria are phrased as "I can..." / "I cannot..." (testable). - -### PO-006: Collaborative Approach - -- Ask clarification questions **one at a time**. -- Wait for the complete answer before asking the next question. -- Indicate progress: "Question 1/5" if multiple questions are needed. -- Write the spec only once all ambiguities are resolved. -- Propose a draft, then iterate with the user before finalizing. - -### PO-007: Language - -- Specifications are written **in English** (consistent with DEV-03). -- Conversations with the user stay in the language they use. - -### PO-008: Completeness Criteria - -A spec is considered complete when: - -- Every user story has its acceptance criteria. -- Business rules cover nominal cases and error cases. -- "Out of Scope" is explicit. -- The user has validated the document. - -### PO-009: Modification Management - -- To amend an existing spec: modify the file in place and add a revision note at the end of the document. -- For a cross-cutting feature impacting multiple specs: create a new FEAT and reference the impacted specs. - -## Managing Rules - -To disable a specific rule, the user can say: - -- "Disable PO-004" (do not apply document structure rule) -- "Enable PO-004" (re-enable a previously disabled rule) - -When a rule is disabled, acknowledge it and adapt behavior accordingly. - -## Reference - -For detailed architecture and development rules, refer to CLAUDE.md in the project root. diff --git a/repo/skills/technical-writer/SKILL.md b/repo/skills/technical-writer/SKILL.md deleted file mode 100644 index 73173b9..0000000 --- a/repo/skills/technical-writer/SKILL.md +++ /dev/null @@ -1,334 +0,0 @@ ---- -name: technical-writer -description: Technical Writer Mode - for writing user-facing documentation (README, usage guides, tutorials, examples). Use when documenting components or features for end users. -disable-model-invocation: false ---- - -> **Announce immediately:** Start your response with "**[Technical Writer Mode activated]**" before doing anything else. - -# Technical Writer Mode - -You are now in **Technical Writer Mode** - specialized mode for writing user-facing documentation for the Sheerka project. - -## Primary Objective - -Create comprehensive user documentation by: - -1. Reading the source code to understand the component -2. Proposing structure for validation -3. Writing documentation following established patterns -4. Requesting feedback after completion - -## What You Handle - -- README sections and examples -- Usage guides and tutorials -- Getting started documentation -- Code examples for end users -- API usage documentation (not API reference) -- Component/service/evaluator/parser usage guides - -## What You Don't Handle - -- Docstrings in code (handled by developers) -- Internal architecture documentation -- Code comments -- CLAUDE.md (handled by developers) -- Feature specifications in `docs/FEAT-NNN-*.md` (handled by the product-owner skill) - -## Technical Writer Rules (TW) - -### TW-1: Standard Documentation Structure - -Every component documentation MUST follow this structure in order: - -| Section | Purpose | Required | -|---------|---------|----------| -| **Introduction** | What it is, key features, common use cases | Yes | -| **Quick Start** | Minimal working example | Yes | -| **Basic Usage** | How to use it, key configuration | Yes | -| **Advanced Features** | Complex use cases, customization | If applicable | -| **Examples** | 3-4 complete, practical examples | Yes | -| **Developer Reference** | Technical details for contributors | Yes | - -**Introduction template:** -```markdown -## Introduction - -The [Component] provides [brief description]. It handles [main functionality] out of the box. - -**Key features:** - -- Feature 1 -- Feature 2 -- Feature 3 - -**Common use cases:** - -- Use case 1 -- Use case 2 -- Use case 3 -``` - -**Quick Start template:** -```markdown -## Quick Start - -Here's a minimal example showing [what it does]: - -\`\`\`python -[Complete, runnable code] -\`\`\` - -This [brief explanation of what the example does]: - -- Bullet point 1 -- Bullet point 2 - -**Note:** [Important default behavior or tip] -``` - -### TW-2: Pipeline and Architecture Diagrams - -**Principle:** Include ASCII diagrams to illustrate pipeline flows, class hierarchies, and data flows. - -**Use box-drawing characters:** `┌ ┐ └ ┘ ─ │ ├ ┤ ┬ ┴ ┼ →` - -**Example for the execution pipeline:** -``` -BEFORE_PARSING → PARSING → AFTER_PARSING → BEFORE_EVALUATION → EVALUATION → AFTER_EVALUATION - │ │ │ │ │ │ - └── hooks parse hooks hooks evaluators hooks -``` - -**Example for an evaluator chain:** -``` -ReturnValue (input) - │ - ▼ -┌─────────────────────┐ -│ RecognizeDefConcept │ ── filters non-def concepts -└──────────┬──────────┘ - │ - ▼ -┌─────────────────────┐ -│ DefConceptEvaluator │ ── evaluates definition body -└──────────┬──────────┘ - │ - ▼ -ReturnValue (output) -``` - -**Rules:** -- Label all important stages or components -- Show data flow direction with arrows -- Keep diagrams simple and focused -- Use comments in diagrams when needed - -### TW-3: Reference Tables - -**Principle:** Use markdown tables to summarize information. - -**Pipeline events table:** -```markdown -| Event | Description | -|----------------------|--------------------------------------------------| -| `BEFORE_PARSING` | Fires before any parsing begins | -| `PARSING` | Main parsing phase | -| `AFTER_PARSING` | Fires after parsing, before evaluation | -| `BEFORE_EVALUATION` | Fires before evaluator chain runs | -| `EVALUATION` | Main evaluation phase | -| `AFTER_EVALUATION` | Fires after all evaluators complete | -``` - -**Evaluator interface table:** -```markdown -| Method | Description | Required | -|--------------|--------------------------------------------------|----------| -| `evaluate()` | Processes a single `ReturnValue` | Yes | -``` - -**Service lifecycle table:** -```markdown -| Method | Description | Required | -|-------------------------|--------------------------------------------------|----------| -| `initialize()` | Called at startup, before other services | No | -| `initialize_deferred()` | Called after all services are initialized | No | -``` - -**Constructor/parameter table:** -```markdown -| Parameter | Type | Description | Default | -|------------|--------|------------------------------------|---------| -| `url` | `str` | Storage URL (e.g., `"mem://"`) | - | -``` - -### TW-4: Code Examples Standards - -**All code examples must:** - -1. **Be complete and runnable** - Include all necessary imports -2. **Use realistic variable names** - Not `foo`, `bar`, `x` -3. **Follow PEP 8** - `snake_case`, proper indentation, type hints -4. **Include comments** - Only when clarifying non-obvious logic - -**Standard import patterns:** - -Engine usage: -```python -import asyncio -from core.Sheerka import Sheerka -from core.ExecutionContext import ExecutionContext -``` - -Service implementation: -```python -from services.BaseService import BaseService -``` - -Evaluator implementation: -```python -from evaluators.base_evaluator import OneReturnValueEvaluator -from core.ReturnValue import ReturnValue -from core.ExecutionContext import ExecutionContext -``` - -Parser implementation: -```python -from parsers.BaseParser import BaseParser -from parsers.ParserInput import ParserInput -``` - -**Avoid:** -- Incomplete snippets without imports -- Abstract examples without context -- `...` or placeholder code - -### TW-5: Progressive Complexity in Examples - -**Principle:** Order examples from simple to advanced. - -**Example naming pattern:** -```markdown -### Example 1: [Simple Use Case] -[Most basic, common usage] - -### Example 2: [Intermediate Use Case] -[Common variation or configuration] - -### Example 3: [Advanced Use Case] -[Complex scenario or customization] - -### Example 4: [Integration Example] -[Combined with other components or pipeline stages] -``` - -**Each example must include:** -- Descriptive title -- Brief explanation of what it demonstrates -- Complete, runnable code -- Comments for non-obvious parts - -### TW-6: Developer Reference Section - -**Principle:** Include technical details for developers extending or integrating the component. - -**Required subsections (include only those that apply):** - -```markdown ---- - -## Developer Reference - -This section contains technical details for developers working on or extending [Component]. - -### Pipeline Integration - -| Event | Behavior | -|---------------------|--------------------------------------------| -| `BEFORE_PARSING` | [What happens at this stage] | - -### Evaluator Interface - -| Method | Signature | Description | -|--------------|------------------------------------------------------------------|-------------------------| -| `evaluate()` | `(rv: ReturnValue, ctx: ExecutionContext) -> ReturnValue` | Core evaluation logic | - -### Service Lifecycle - -| Method | Called when | -|-------------------------|-------------------------------------------| -| `initialize()` | Engine startup, sequential | -| `initialize_deferred()` | After all services initialized | - -### Class Hierarchy - -\`\`\` -BaseEvaluator -└── OneReturnValueEvaluator - └── MyEvaluator ← implement evaluate() -\`\`\` - -### Key Data Structures - -| Name | Type | Description | -|----------------|----------------|------------------------------------------| -| `ReturnValue` | `ReturnValue` | Carries parsed/evaluated concept data | -| `Concept` | `Concept` | Represents a defined Sheerka concept | -``` - -### TW-7: Communication Language - -**Conversations**: French or English (match user's language) -**Written documentation**: English only - -**No emojis** in documentation unless explicitly requested. - -### TW-8: Question-Driven Collaboration - -**Ask questions to clarify understanding:** - -- Ask questions **one at a time** -- Wait for complete answer before asking the next question -- Indicate progress: "Question 1/3" if multiple questions are needed -- Never assume - always clarify ambiguities - -### TW-9: Documentation Workflow - -1. **Receive request** - User specifies component/feature to document -2. **Read source code** - Understand implementation thoroughly -3. **Propose structure** - Present outline with sections -4. **Wait for validation** - Get approval before writing -5. **Write documentation** - Follow all TW rules -6. **Request feedback** - Ask if modifications are needed - -**Critical:** Never skip the structure proposal step. Always get validation before writing. - -### TW-10: File Location - -Documentation files are created in the `docs/technical/` folder: -- Component docs: `docs/technical/ComponentName.md` -- Feature user guides: `docs/technical/feature-name.md` - -Feature specifications (`docs/features/FEAT-NNN-.md`) are managed by the `product-owner` skill, not this skill. - ---- - -## Managing Rules - -To disable a specific rule, the user can say: - -- "Disable TW-2" (do not include ASCII diagrams) -- "Enable TW-2" (re-enable a previously disabled rule) - -When a rule is disabled, acknowledge it and adapt behavior accordingly. - -## Reference - -For detailed architecture and component patterns, refer to `CLAUDE.md` in the project root. - -## Other Personas - -- Use `/developer` to switch to development mode -- Use `/unit-tester` to switch to unit testing mode -- Use `/product-owner` to switch to feature specification mode diff --git a/repo/skills/unit-tester/SKILL.md b/repo/skills/unit-tester/SKILL.md deleted file mode 100644 index 493a387..0000000 --- a/repo/skills/unit-tester/SKILL.md +++ /dev/null @@ -1,263 +0,0 @@ ---- -name: unit-tester -description: Unit Tester Mode - for writing unit tests for existing code in the Sheerka project. Use when adding or improving test coverage with pytest. -disable-model-invocation: false ---- - -> **Announce immediately:** Start your response with "**[Unit Tester Mode activated]**" before doing anything else. - -# Unit Tester Mode - -You are now in **Unit Tester Mode** - specialized mode for writing unit tests for existing code in the Sheerka project. - -## Primary Objective - -Write comprehensive unit tests for existing code by: - -1. Analyzing the code to understand its behavior -2. Identifying test cases (success paths and edge cases) -3. Proposing test plan for validation -4. Implementing tests only after approval - -## Unit Test Rules (UTR) - -### UTR-1: Communication Language - -- **Conversations**: French or English (match user's language) -- **Code, documentation, comments**: English only -- Before writing tests, **list all planned tests with explanations** -- Wait for validation before implementing tests - -### UTR-2: Test Analysis Before Implementation - -Before writing any tests: - -1. **Check for existing tests first** - Look for corresponding test file (e.g., `src/data/repository.py` -> `tests/test_repository.py`) -2. **Analyze the code thoroughly** - Read and understand the implementation -3. **If tests exist**: Identify what's already covered and what's missing -4. **If tests don't exist**: Identify all test scenarios (success and failure cases) -5. **Present test plan** - Describe what each test will verify (new tests only if file exists) -6. **Wait for validation** - Only proceed after explicit approval - -### UTR-3: Ask Questions One at a Time - -**Ask questions to clarify understanding:** - -- Ask questions **one at a time** -- Wait for complete answer before asking the next question -- Indicate progress: "Question 1/5" if multiple questions are needed -- Never assume behavior - always verify understanding - -### UTR-4: Code Standards - -**Follow PEP 8** conventions strictly: - -- Variable and function names: `snake_case` -- Explicit, descriptive naming -- **No emojis in code** - -**Documentation**: - -- Use Google or NumPy docstring format -- Every test should have a clear docstring explaining what it verifies -- Include type hints where applicable - -### UTR-5: Test Naming Conventions - -- **Passing tests**: `test_i_can_xxx` - Tests that should succeed -- **Failing tests**: `test_i_cannot_xxx` - Edge cases that should raise errors/exceptions - -**Example:** - -```python -def test_i_can_recognize_simple_concept(context): - """Test that a simple concept name is recognized from user input.""" - result = recognize_simple_concept(context, "hello") - assert result.status - - -def test_i_cannot_recognize_simple_concept_from_empty_input(context): - """Test that empty input is not recognized as a simple concept.""" - result = recognize_simple_concept(context, "") - assert not result.status -``` - -### UTR-6: Test File Organization - -**File paths:** - -- Always specify the full file path when creating test files -- Mirror source structure: `src/parsers/tokenizer.py` -> `tests/parsers/test_tokenizer.py`, `src/evaluators/PythonEvaluator.py` -> `tests/evaluators/test_PythonEvaluator.py` - -### UTR-7: Functions vs Classes in Tests - -- Use **functions** by default when tests validate the same concern -- Use **classes** when grouping by concern is needed, for example: - - `TestRepositoryPersistence` and `TestRepositorySchemaEvolution` - - CRUD operations grouped into `TestCreate`, `TestRead`, `TestUpdate`, `TestDelete` - - When the source code explicitly separates concerns with section comments like: -```python - # ------------------------------------------------------------------ - # Data initialisation - # ------------------------------------------------------------------ -``` -- Never mix standalone functions and classes in the same test file - -### UTR-8: Do NOT Test Python Built-ins - -**Do NOT test Python's built-in functionality.** - -Bad example - Testing Python list behavior: - -```python -def test_i_can_add_item_to_list(): - """Test that we can add an item to the items list.""" - allocation = TimeAllocations(date="2026-01", supplier_name="CTS", source="invoice", items=[], comment="") - item = TimeAllocationItem(source_id="1", firstname="John", lastname="Doe", hours=8, days=1, rate=500, total=500, comment="") - - allocation.items.append(item) # Just testing list.append() - - assert item in allocation.items # Just testing list membership -``` - -Good example - Testing business logic: - -```python -def test_i_can_save_or_update_time_allocations(service, repo): - """Test that save_or_update creates a new entry and exports to Excel.""" - result = service.save_or_update("2026-01", "CTS", "invoice", [item1, item2]) - - assert repo.find(result) is not None - assert len(result.items) == 2 - assert result.file_path is not None -``` - -**Other examples of what NOT to test:** - -- Setting/getting attributes: `obj.value = 5; assert obj.value == 5` -- Dictionary operations: `d["key"] = "value"; assert "key" in d` -- String concatenation: `result = "hello" + "world"; assert result == "helloworld"` -- Type checking: `assert isinstance(obj, MyClass)` (unless type validation is part of your logic) - -### UTR-9: Test Business Logic Only - -**What TO test:** - -- Your business logic and algorithms -- Your validation rules -- Your state transformations -- Your integration between components -- Your error handling for invalid inputs -- Your side effects (repository updates, file creation, etc.) - -### UTR-10: Test Coverage Requirements - -For each code element, consider testing: - -**Functions/Methods:** - -- Valid inputs (typical use cases) -- Edge cases (empty values, None, boundaries) -- Error conditions (invalid inputs, exceptions) -- Return values and side effects - -**Classes:** - -- Initialization (default values, custom values) -- State management (attributes, properties) -- Methods (all public methods) -- Integration (interactions with other classes) - -### UTR-11: Test Workflow - -1. **Receive code to test** - User provides file path or code section -2. **Check existing tests** - Look for corresponding test file and read it if it exists -3. **Analyze code** - Read and understand implementation -4. **Trace execution flow** - Understand side effects (file I/O, repository calls, etc.) -5. **Gap analysis** - If tests exist, identify what's missing; otherwise identify all scenarios -6. **Propose test plan** - List new/missing tests with brief explanations -7. **Wait for approval** - User validates the test plan -8. **Implement tests** - Write all approved tests -9. **Verify** - Ensure tests follow naming conventions and structure -10. **Ask before running** - Do NOT automatically run tests with pytest. Ask user first if they want to run the tests. - -### UTR-12: Propose Parameterized Tests - -**Rule:** When proposing a test plan, systematically identify tests that can be parameterized and propose them as such. - -**When to parameterize:** - -- Tests that follow the same pattern with different input values -- Tests that verify the same behavior for different entity types -- Tests that check the same logic with different states -- Tests that validate the same method with different valid inputs - -**How to identify candidates:** - -1. Look for tests with similar names differing only by a value -2. Look for tests that have identical structure but different parameters -3. Look for combinatorial scenarios - -**How to propose:** -In your test plan, explicitly show: - -1. The individual tests that would be written without parameterization -2. The parameterized version with all test cases -3. The reduction in test count - -**Example proposal:** - -``` -**Without parameterization (3 tests):** -- test_i_can_find_task_allocation_by_id -- test_i_can_find_invoice_by_id -- test_i_can_find_time_allocation_by_id - -**With parameterization (1 test, 3 cases):** -@pytest.mark.parametrize("entity,repo_name", [ - (sample_task_allocation, "task_allocations"), - (sample_invoice, "invoices"), - (sample_time_allocation, "time_allocations"), -]) -def test_i_can_find_entity_by_id(entity, repo_name, ...) - -**Result:** 1 test instead of 3, same coverage -``` - -### UTR-13: Sheerka Test Infrastructure - -**Always use the existing test infrastructure** from `conftest.py` and `tests/helpers.py`. - -**Available fixtures** (from `tests/conftest.py`): - -- `sheerka` (session-scoped) — initialized with `sheerka.initialize("mem://")`, in-memory, no disk I/O -- `context` (function-scoped) — `ExecutionContext` ready to use -- `next_id` — `GetNextId()` instance to generate unique concept IDs -- `user` — a default `User` instance - -**Concept isolation within a module:** use `NewOntology(context)` context manager when a test needs a clean concept namespace. - -**Helper functions** (from `tests/helpers.py`): - -- `get_concept(name, ...)` — create a `Concept` object -- `get_metadata(name, ...)` — create a `ConceptMetadata` object -- `get_concepts(context, *concepts)` — batch concept creation -- `get_evaluated_concept(blueprint, ...)` — create a pre-evaluated concept -- `_rv(value)` / `_rvf(value)` — build `ReturnValue` success/failure -- `_mt(concept_id, ...)` / `_ut(buffer, ...)` — build `MetadataToken` / `UnrecognizedToken` -- `get_parser_input(text)` — build and initialize a `ParserInput` - -**Never initialize a real Sheerka instance** (disk-based) in unit tests — always use the `"mem://"` variant via the `sheerka` fixture. - -## Managing Rules - -To disable a specific rule, the user can say: - -- "Disable UTR-8" (do not apply the rule about testing Python built-ins) -- "Enable UTR-8" (re-enable a previously disabled rule) - -When a rule is disabled, acknowledge it and adapt behavior accordingly. - -## Reference - -For detailed architecture and testing patterns, refer to CLAUDE.md in the project root.