From 56360ecfac78e40ccfb6adaeab6e5d1a695811b5 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Nov 2025 06:05:48 +0000 Subject: [PATCH] Select next task: Prototype experimental macro for conditional specification composition This selection record documents the evaluation and prioritization of P2 backlog items for SpecificationKit v3.0.0+. After analyzing candidate items, the experimental macro prototype task was selected as the highest-value unblocked work item. Selection criteria: - No external blockers (vs. benchmark capture requiring macOS hardware) - Self-contained scope (vs. performance optimization depending on benchmarks) - Clear evaluation criteria (three macro options: @specsIf, #composed, @deriveSpec) - Demonstrates macro system evolution and library maturity - Unblocks future design decisions for macro roadmap Selection record: AGENTS_DOCS/INPROGRESS/2025-11-17_NextTask_ExperimentalMacroPrototype.md See DOCS/COMMANDS/SELECT_NEXT.md for selection procedure details. --- ...-17_NextTask_ExperimentalMacroPrototype.md | 104 ++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 AGENTS_DOCS/INPROGRESS/2025-11-17_NextTask_ExperimentalMacroPrototype.md diff --git a/AGENTS_DOCS/INPROGRESS/2025-11-17_NextTask_ExperimentalMacroPrototype.md b/AGENTS_DOCS/INPROGRESS/2025-11-17_NextTask_ExperimentalMacroPrototype.md new file mode 100644 index 0000000..e2dff53 --- /dev/null +++ b/AGENTS_DOCS/INPROGRESS/2025-11-17_NextTask_ExperimentalMacroPrototype.md @@ -0,0 +1,104 @@ +# Next Task — Prototype Experimental Macro for Conditional Specification Composition + +## Selection Metadata +- **Selection Date:** 2025-11-17 +- **Chosen Task:** Prototype one experimental macro from the P2 enhancement set, evaluating `@specsIf(condition:)`, `#composed(...)`, or `@deriveSpec(from:)` syntax options and providing usage examples +- **Source Backlog Entries:** + - `AGENTS_DOCS/markdown/3.0.0/00_3.0.0_TODO_SpecificationKit.md` lines 25–27 (Experimental Features, P2) +- **Status:** Selected / Ready to plan implementation +- **Blocking Issues:** None + +## Candidate Review + +### Evaluated Options +1. **Benchmark Baseline Capture** (P2.2 Performance Optimization) + - Referenced: `AGENTS_DOCS/markdown/00_SpecificationKit_TODO.md` line 110 + - Status: **Blocked** — requires macOS hardware for CoreData-dependent tests + - Mitigation: Can be triggered via GitHub Actions when hardware access is scheduled + - Decision: Defer until macOS CI access available + +2. **Prototype Experimental Macro** (P2 Experimental Features) + - Referenced: `AGENTS_DOCS/markdown/3.0.0/00_3.0.0_TODO_SpecificationKit.md` lines 25–27 + - Status: **Unblocked** — self-contained, requires no external resources + - Scope: Three concrete macro options to evaluate + - Decision: **SELECTED** for implementation + +3. **Performance Optimization Investigation** (P2 Performance Optimization) + - Referenced: `AGENTS_DOCS/markdown/3.0.0/00_3.0.0_TODO_SpecificationKit.md` lines 29–32 + - Status: Unblocked but requires baseline metrics first + - Dependency: Benchmark baseline capture (currently blocked) + - Decision: Defer until benchmarks are available for comparison + +### Why This Task Now + +1. **No external blockers** — Can proceed independently without waiting for macOS hardware or other infrastructure +2. **Demonstrates macro evolution** — Extends the existing macro system (`@specs`, `@AutoContext`) with a new, more advanced capability +3. **Clear evaluation criteria** — Three specific macro options with concrete semantics to compare +4. **High visibility** — Experimental features are often showcased in release notes and documentation +5. **Unblocks future design** — Results inform future macro system roadmap (v3.1.0+) +6. **Library maturity indicator** — Shows SpecificationKit is actively evolving with advanced patterns + +## Implementation Notes + +### Entry Points / Files to Inspect +- `Sources/SpecificationKitMacros/MacroPlugin.swift` — Macro registration entry point +- `Sources/SpecificationKitMacros/AutoContextMacro.swift` — Example of advanced macro implementation with diagnostics +- `Sources/SpecificationKitMacros/SpecsMacro.swift` — Example of composite specification macro +- `Tests/SpecificationKitMacrosTests/` — Macro test patterns using swift-macro-testing +- `CONTRIBUTING.md` — Macro development guidelines +- `CLAUDE.md` — Build and test commands for macro validation + +### Macro Options to Evaluate + +**Option 1: `@specsIf(condition:)`** +- Syntax: `@specsIf(condition: { context in context.isSubscribed })` +- Behavior: Wraps a specification to conditionally enable/disable based on a closure +- Pros: Simple, closure-based approach +- Cons: May require runtime evaluation overhead + +**Option 2: `#composed(...)`** +- Syntax: `#composed([spec1, spec2, spec3], operator: .all)` or similar +- Behavior: Compile-time composition of multiple specs with operator selection +- Pros: Explicit operator choice, potential for compile-time optimizations +- Cons: Declarative syntax may feel inconsistent with attribute macros + +**Option 3: `@deriveSpec(from:)`** +- Syntax: `@deriveSpec(from: MyComposableProtocol.self)` +- Behavior: Generate specification from a protocol conformance +- Pros: Protocol-driven, extensible pattern +- Cons: Complex implementation, may require protocol synthesis + +### Acceptance Thoughts +- Fully working prototype of one chosen macro syntax +- Comprehensive test coverage (at minimum 5 test cases) demonstrating: + - Basic usage + - Edge cases (empty specs, nil conditions, etc.) + - Error handling and diagnostics + - Integration with existing specs (`@Satisfies`, `@Decides`) +- Usage example in documentation or README +- Diagnostic messages that guide users on correct usage +- No breaking changes to existing macros +- Builds without warnings on Swift 5.9+ + +### Open Questions / Risks +1. **Macro complexity** — Does the chosen syntax require advanced macro capabilities, or can it be implemented with current Swift 5.9 macro system? +2. **Performance impact** — Does the generated code add overhead compared to manual composition? +3. **User ergonomics** — Is the syntax intuitive for the intended use case? +4. **Maintenance burden** — Can the macro be documented and maintained alongside existing macros? + +## Immediate Next Actions +1. Read macro implementation examples in `Sources/SpecificationKitMacros/` to understand existing patterns +2. Design the chosen macro's syntax and semantics (evaluation criteria needed before selection) +3. Implement macro in `MacroPlugin.swift` with diagnostic support +4. Write 5+ comprehensive test cases in `SpecificationKitMacrosTests/` +5. Add usage documentation to `CONTRIBUTING.md` or create a new macro guide +6. Run full test suite and validate build with `swift build -v` +7. Update CHANGELOG.md with new P2 feature entry +8. Archive this selection record and document results in a new task archive + +## Reference Documents +- **Base TODO**: `AGENTS_DOCS/markdown/00_SpecificationKit_TODO.md` +- **v3.0.0 TODO**: `AGENTS_DOCS/markdown/3.0.0/00_3.0.0_TODO_SpecificationKit.md` +- **Blockers**: `AGENTS_DOCS/INPROGRESS/blocked.md` +- **Archive Summary**: `AGENTS_DOCS/TASK_ARCHIVE/ARCHIVE_SUMMARY.md` +- **Macro Examples**: `Sources/SpecificationKitMacros/*.swift`