x-ipe 1.0.23__py3-none-any.whl → 1.0.25__py3-none-any.whl

x_ipe/resources/skills/task-type-code-implementation/SKILL.md

@@ -74,6 +74,7 @@ Output:
 | 3 | Technical design document exists | Yes |
 | 4 | **Tests exist from Test Generation task** | Yes |
 | 5 | **All tests currently FAIL (TDD ready)** | Yes |
+| 6 | **Tracing utility exists in project** | Yes (see Tracing Check) |
 
 **⚠️ PRE-CODING VERIFICATION:**
 Before writing ANY implementation code, agent MUST:
@@ -81,6 +82,12 @@ Before writing ANY implementation code, agent MUST:
 2. Verify tests FAIL (proving no implementation yet)
 3. If tests pass or don't exist → STOP and complete Test Generation first
 
+**🔍 TRACING CHECK (FEATURE-023-D):**
+Before implementing, verify tracing infrastructure exists:
+1. Check for `tracing/` directory or `x_ipe.tracing` import availability
+2. If NOT available → Use `tool-tracing-creator` skill to create tracing utility
+3. If available → Proceed with implementation
+
 ---
 
 ## Execution Flow
@@ -105,105 +112,17 @@ Execute Code Implementation by following these steps in order:
 
 ## Implementation Principles
 
-### KISS (Keep It Simple, Stupid)
-
-- Write simple, readable code
-- No complex abstractions unless specified in design
-- Use standard patterns from technical design
-- Prefer clarity over cleverness
-- If implementation seems complex, question the design
-
----
-
-### YAGNI (You Aren't Gonna Need It)
-
-- Implement ONLY what's in technical design
-- No extra features "just in case"
-- No "nice to have" additions
-- If it's not in the design doc, don't implement it
-- Defer future features to future tasks
-
----
-
-### Test Driven Development (TDD)
-
-**Workflow:**
-```
-1. Write test (RED - test fails)
-2. Write minimum code to pass (GREEN - test passes)
-3. Refactor if needed (REFACTOR - clean up)
-4. Repeat
-```
-
----
-
-### 🎨 Mockup Reference (Conditional)
-
-**When implementing frontend code:**
-```
-IF Technical Scope in specification.md includes [Frontend] OR [Full Stack]:
-  1. MUST open and reference "Linked Mockups" from specification.md
-  2. Keep mockup visible during frontend implementation
-  3. Match implementation to mockup:
-     - Component structure and hierarchy
-     - Layout and positioning
-     - Interactive elements and behaviors
-     - Form fields and their validations
-     - Visual states (hover, active, disabled, error)
-  4. Verify implementation visually matches mockup
-  5. Note any deviations and document reasons
-
-ELSE (Backend/API Only/Database/Infrastructure):
-  - Skip mockup reference
-  - Implement based on technical design only
-```
-
-**Implementation Tip:**
-For frontend work, implement in this order:
-1. Component structure (HTML/JSX)
-2. Styling (CSS) to match mockup
-3. Interactivity (event handlers)
-4. State management
-5. API integration
-
----
-
-### ⚠️ Coverage ≠ Complexity
-
-**CRITICAL RULE: DO NOT make code complex just for test coverage!**
+| Principle | Description |
+|-----------|-------------|
+| **KISS** | Keep code simple, readable, prefer clarity over cleverness |
+| **YAGNI** | Implement ONLY what's in technical design, no extras |
+| **TDD** | RED (test fails) → GREEN (pass) → REFACTOR → REPEAT |
+| **Coverage ≠ Complexity** | Target 80%+, never add complexity for coverage |
+| **Coding Standards** | Use linters, formatters, meaningful names |
 
-- Keep code simple and testable
-- Target reasonable coverage (80%+), not 100% at all costs
-- If code is hard to test, simplify the code
-- Avoid testing implementation details
-- Do NOT add parameters, abstractions, or indirection just to hit coverage metrics
+**🎨 Mockup Reference:** For frontend work, reference mockups from specification.md and match layout, components, and visual states.
 
-**Good:**
-```python
-# Simple, testable function
-def calculate_discount(price: float, percent: int) -> float:
-    return price * (1 - percent / 100)
-```
-
-**Bad (DON'T DO THIS):**
-```python
-# Over-complicated just for "testability"
-def calculate_discount(price, percent, 
-                       logger=None, cache=None, 
-                       event_bus=None, metrics=None):
-    # Unnecessary complexity added for coverage
-```
-
----
-
-### Follow Coding Standards
-
-- Follow project coding standards
-- Use linters and formatters
-- Consistent naming conventions
-- Meaningful variable/function names
-- Document public APIs
-- Handle errors appropriately
+📖 **See:** [references/implementation-guidelines.md](references/implementation-guidelines.md) for detailed principles, examples, and coding standards.
 
 ---
 
@@ -231,90 +150,32 @@ RECEIVE Feature Data Model:
 
 ### Step 2: Learn Technical Design Document
 
-**Action:** THOROUGHLY read and understand the technical design before writing any code
+**Action:** THOROUGHLY read and understand the technical design
 
-```
-1. READ {technical_design_link} from Feature Data Model
-   Location: x-ipe-docs/requirements/FEATURE-XXX/technical-design.md
-
-2. UNDERSTAND Part 1 (Agent-Facing Summary):
-   - Components to implement
-   - Key interfaces and signatures
-   - Scope and boundaries
-   - Usage examples
-   - Tags for context
-
-3. UNDERSTAND Part 2 (Implementation Guide):
-   - Data models (exact fields and types)
-   - API endpoints (request/response formats)
-   - Workflows (sequence and logic)
-   - Implementation guidelines (specific notes)
-   - Edge cases and error handling
-
-4. NOTE any references to architecture designs
-
-5. CHECK Design Change Log for any updates since initial design
-```
+1. READ `{technical_design_link}` from Feature Data Model
+2. UNDERSTAND Part 1 (Agent-Facing Summary) and Part 2 (Implementation Guide)
+3. NOTE references to architecture designs
+4. CHECK Design Change Log for updates
 
-**⚠️ STRICT REQUIREMENT:** 
-- Do NOT start coding until you fully understand the technical design!
-- Implementation MUST follow the technical design exactly
-- If design is unclear, incomplete, or incorrect - STOP and update design first
+**⚠️ STRICT:** Do NOT code until design is understood. If design is unclear → STOP and update first.
 
 ---
 
 ### Step 2.1: Update Technical Design If Needed
 
-**Action:** If implementation reveals design issues, UPDATE the design BEFORE proceeding
+If implementation reveals design issues → STOP, UPDATE technical-design.md, add to Design Change Log, then RESUME.
 
-```
-IF during implementation you discover:
-  - Design is not working as expected
-  - Better implementation approach exists
-  - Design needs changes to support feature properly
-  - Key component interfaces need modification
-
-THEN:
-  1. STOP implementation
-  2. UPDATE technical-design.md:
-     - Modify affected sections in Part 1 and/or Part 2
-     - Add entry to Design Change Log:
-       | Date | Phase | Change Summary |
-       |------|-------|----------------|
-       | {today} | Code Implementation | {What changed, why, impact ~100 words} |
-  3. RESUME implementation with updated design
-
-DO NOT:
-  - Implement something different from the design without updating it
-  - Make incompatible changes to key components without documenting
-  - Skip the change log entry
-```
+📖 **See:** [references/implementation-guidelines.md](references/implementation-guidelines.md#design-update-procedure) for detailed procedure.
 
 ---
 
 ### Step 3: Read Architecture Designs (If Referenced)
 
-**Action:** If technical design mentions common architecture rules, READ them first
-
-```
-IF technical design references architecture components:
-  1. READ x-ipe-docs/architecture/technical-designs/{component}.md
-  2. UNDERSTAND:
-     - Common patterns to follow
-     - Required interfaces/protocols
-     - Shared utilities to use
-     - Integration requirements
-
-COMMON REFERENCES:
-  - Database patterns
-  - API standards
-  - Error handling conventions
-  - Logging standards
-  - Security patterns
-  - Authentication/Authorization
-```
+**Action:** If technical design references architecture patterns, READ them first
 
-**IMPORTANT:** Architecture designs define project-wide patterns. Follow them consistently!
+- Read `x-ipe-docs/architecture/technical-designs/{component}.md`
+- Understand common patterns, interfaces, and integration requirements
+- Follow project-wide patterns consistently
 
 ---
 
@@ -322,51 +183,15 @@ COMMON REFERENCES:
 
 **Action:** Verify tests from Test Generation are ready BEFORE any coding
 
-```
-1. LOCATE test files created by Test Generation task:
-   - tests/unit/{feature}/
-   - tests/integration/{feature}/
-   - tests/api/{feature}/
-   - tests/test_{feature}.py
-
-2. RUN all tests to verify baseline:
-   - pytest tests/ -v (Python)
-   - npm test (Node.js)
-   
-3. VERIFY tests FAIL:
-   - ⚠️ All feature-related tests should FAIL
-   - This proves no implementation exists yet
-   - Document: "X tests failing, 0 passing (TDD ready)"
-
-4. IF tests pass:
-   - STOP: Implementation may already exist
-   - Review what code exists
-   - Determine if this is a duplicate task
-
-5. IF tests don't exist:
-   - ⚠️ STOP immediately
-   - Report: "Test Generation task not completed"
-   - Go back to Test Generation task FIRST
-   - Do NOT proceed without tests
-
-6. UNDERSTAND what tests expect:
-   - Review test assertions
-   - Note expected inputs/outputs
-   - Identify test structure
-```
+1. **LOCATE** test files: `tests/unit/{feature}/`, `tests/integration/{feature}/`, `tests/test_{feature}.py`
+2. **RUN** all tests: `pytest tests/ -v` or `npm test`
+3. **VERIFY** tests FAIL (proves TDD ready)
+4. **IF tests pass** → STOP, implementation may exist
+5. **IF tests don't exist** → STOP, complete Test Generation first
 
-**⚠️ NO EXCEPTIONS:**
-- Do NOT write any implementation code until Step 4 is complete
-- Do NOT skip this step even if you "know" what to implement
-- Tests MUST exist and MUST fail before proceeding
+**⚠️ NO EXCEPTIONS:** Do NOT write implementation code until tests exist AND fail.
 
-**TDD Workflow:**
-```
-RED → Tests fail (current state after Step 4)
-GREEN → Write minimum code to pass (Step 5)
-REFACTOR → Improve code quality
-REPEAT → Until all tests pass
-```
+📖 **See:** [references/implementation-guidelines.md](references/implementation-guidelines.md#step-4-load-tests-detailed) for detailed procedure.
 
 ---
 
@@ -374,44 +199,13 @@ REPEAT → Until all tests pass
 
 **Action:** Write minimum code to pass tests (following technical design)
 
-**🌐 Web Search (As Needed):**
-Use web search capability when you encounter:
-- Library/framework API questions → Search official documentation
-- Error messages → Search Stack Overflow, GitHub Issues
-- Implementation patterns → Search for best practices
-- Performance issues → Search for optimization techniques
-- Security concerns → Search for secure coding practices
+1. **IMPLEMENT** in order: Data models → Business logic → API endpoints → Integration
+2. **FOR EACH** component: Write code → Run tests → Verify pass → Refactor if needed
+3. **AVOID:** Extra features, over-engineering, premature optimization
 
-```
-1. IMPLEMENT in order specified by technical design:
-   - Data models
-   - Business logic/services
-   - API endpoints (if applicable)
-   - Integration points
-
-2. FOR EACH component:
-   - Write code following technical design exactly
-   - Run related tests
-   - Verify tests pass (GREEN phase)
-   - Refactor if needed (keep simple!)
-   - Verify tests still pass
-
-3. AVOID:
-   - Adding features not in design
-   - Over-engineering
-   - Premature optimization
-   - Complex abstractions
-```
+**🌐 Web Search:** Use for library APIs, error messages, best practices, security.
 
-**Implementation Structure:**
-```
-src/
-├── models/         # Data models from design
-├── services/       # Business logic from design
-├── routes/         # API endpoints from design (if applicable)
-├── middleware/     # Cross-cutting concerns
-└── utils/          # Helper functions
-```
+📖 **See:** [references/implementation-guidelines.md](references/implementation-guidelines.md#step-5-implement-code-detailed) for detailed procedure.
 
 ---
 
@@ -419,30 +213,28 @@ src/
 
 **Action:** Run all checks before completion
 
-```
-1. RUN all tests:
-   - pytest tests/ -v (Python)
-   - npm test (Node.js)
-
-2. CHECK coverage (aim for 80%+, but don't add complexity for it):
-   - pytest --cov=src tests/
-
-3. RUN linter:
-   - ruff check src/ tests/
-   - flake8 src/ tests/
-   - eslint src/ tests/
-
-4. RUN formatter:
-   - ruff format src/ tests/
-   - black src/ tests/
-   - prettier --write src/ tests/
-
-5. VERIFY:
-   - [ ] All tests pass
-   - [ ] No linter errors
-   - [ ] Code matches technical design
-   - [ ] No extra features added
-```
+1. **RUN** tests: `pytest tests/ -v` or `npm test`
+2. **CHECK** coverage: `pytest --cov=src tests/` (aim 80%+)
+3. **RUN** linter: `ruff check` / `eslint`
+4. **RUN** formatter: `ruff format` / `prettier`
+5. **VERIFY:** All tests pass, no linter errors, code matches design
+
+📖 **See:** [references/implementation-guidelines.md](references/implementation-guidelines.md#step-6-verify--ensure-quality-detailed) for detailed commands.
+
+---
+
+### Step 7: Apply Tracing Instrumentation (FEATURE-023-D)
+
+**Action:** Add tracing decorators to all implemented code
+
+1. **INVOKE** `tool-tracing-instrumentation` skill for all modified files
+2. **REVIEW** proposed decorators (INFO for public, DEBUG for helpers)
+3. **APPLY** decorators with sensitive param redaction
+4. **RE-RUN** tests to verify functionality
+
+**Skip if:** No tracing infrastructure, test files, or config files.
+
+📖 **See:** [references/implementation-guidelines.md](references/implementation-guidelines.md#tracing-instrumentation) for detailed procedure.
 
 ---
 
@@ -459,6 +251,16 @@ src/
 | 7 | Code is simple (KISS) | Yes |
 | 8 | Linter passes | Yes |
 | 9 | Test coverage ≥ 80% for new code | Recommended |
+| 10 | **All public functions have `@x_ipe_tracing` decorators** | Yes |
+| 11 | **Sensitive parameters have `redact=[]` specified** | Yes |
+
+**🔍 TRACING VERIFICATION (FEATURE-023-D):**
+Before marking complete, verify tracing is applied:
+1. All API endpoints have `@x_ipe_tracing(level="INFO")`
+2. Key business functions have `@x_ipe_tracing(level="INFO")`
+3. Helper/utility functions have `@x_ipe_tracing(level="DEBUG")` or are skipped
+4. Sensitive parameters (password, token, secret, key) have `redact=["param"]`
+5. Use `tool-tracing-instrumentation` skill to add decorators if missing
 
 **Important:** After completing this skill, always return to `task-execution-guideline` skill to continue the task execution flow and validate the DoD defined there.