From 2be8987e2cb86b7219e9ead13e960c2c286cc952 Mon Sep 17 00:00:00 2001 From: Kodjo Sossouvi Date: Mon, 13 Apr 2026 21:28:32 +0200 Subject: [PATCH] first version --- repo/CLAUDE.md | 83 +++++++ repo/skills/developer/SKILL.md | 126 ++++++++++ repo/skills/product-owner/SKILL.md | 96 ++++++++ repo/skills/technical-writer/SKILL.md | 334 ++++++++++++++++++++++++++ repo/skills/unit-tester/SKILL.md | 263 ++++++++++++++++++++ 5 files changed, 902 insertions(+) create mode 100644 repo/CLAUDE.md create mode 100644 repo/skills/developer/SKILL.md create mode 100644 repo/skills/product-owner/SKILL.md create mode 100644 repo/skills/technical-writer/SKILL.md create mode 100644 repo/skills/unit-tester/SKILL.md diff --git a/repo/CLAUDE.md b/repo/CLAUDE.md new file mode 100644 index 0000000..23fd4aa --- /dev/null +++ b/repo/CLAUDE.md @@ -0,0 +1,83 @@ +# [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 new file mode 100644 index 0000000..acbd289 --- /dev/null +++ b/repo/skills/developer/SKILL.md @@ -0,0 +1,126 @@ +--- +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 new file mode 100644 index 0000000..7cc829a --- /dev/null +++ b/repo/skills/product-owner/SKILL.md @@ -0,0 +1,96 @@ +--- +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 new file mode 100644 index 0000000..73173b9 --- /dev/null +++ b/repo/skills/technical-writer/SKILL.md @@ -0,0 +1,334 @@ +--- +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 new file mode 100644 index 0000000..493a387 --- /dev/null +++ b/repo/skills/unit-tester/SKILL.md @@ -0,0 +1,263 @@ +--- +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.