@ai-content-space/loopx 0.1.10 → 0.2.1

package/plugins/loopx/skills/review/SKILL.md

@@ -1,139 +1,106 @@
 ---
 name: review
-description: "Reviews a loopx build execution record for acceptance, code risks, evidence quality, and architecture smells. Not for doing implementation work or replanning."
-when_to_use: "review, code review, acceptance, go no-go, execution-record, architecture smell, build complete, 审查, 验收"
+description: "Dispatches a loopx code reviewer subagent against a concrete git range and requirements. Not for implementation, planning, or unresolved review scope."
+when_to_use: "request code review, completed task review, major feature review, pre-merge review, subagent code quality check"
 metadata:
-  version: "0.1.10"
-argument-hint: "<execution-record path or workflow slug>"
+  version: "0.2.1"
 ---
 
-# loopx Review
+# Review
 
-## Purpose
+Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
 
-Repo-local acceptance surface for loopx. Use it to evaluate the execution package from `build` and return an explicit go / no-go result.
+**Core principle:** Review early, review often.
 
-## Inputs
+## When to Request Review
 
-Preferred skill input:
+**Mandatory:**
+- After each task in subagent-exec
+- After completing major feature
+- Before merge to main
 
-- `.loopx/workflows/<slug>/execution-record.md`
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
 
-Compatible skill / CLI input:
+## How to Request
 
-- `<slug>`
-
-When invoked with an execution record path, derive `<slug>` from the workflow directory and evaluate the matching active run.
-
-When present, use `.loopx/config.json` as supporting context for project-native verification commands, existing AI rule files, and existing spec sources. Do not treat those external or pre-existing sources as replacements for the loopx execution record and review artifact.
-
-## Expected Outputs
-
-- a review artifact tied to the run being evaluated
-- verdict and rationale
-- code review findings for the implementation diff, including file / line references when issues are found
-- architecture-smell findings from the internal review lane, focused on module depth, test seams, domain vocabulary, duplicated rules, and plan architecture alignment
-- rollback/fix guidance when execution is incomplete, unstable, or needs another iteration
-- an explicit `Next:` block with the exact next skill command when more work remains
-
-## User Notification Language
-
-The final user-facing review result must be written in Chinese.
-
-Use stable machine values only where they are commands, file paths, JSON/state fields, or exact verdict identifiers. The human-readable summary, rationale, findings, residual risks, rollback guidance, and next-step instruction must be Chinese.
-
-## Decision Boundary
-
-- Use this only after build has produced execution and verification evidence for a specific run.
-- Stop here if review evidence is incomplete. `review` remains an independent gate and does not auto-complete the workflow.
-- Review must include code review of the build-owned implementation diff. Do not limit review to artifact/schema checks.
-- Review should compare verification evidence against project-native commands recorded in `.loopx/config.json` when available, while still accepting stronger task-specific verification from the approved plan.
-- Review must include the architecture-smell lane as part of review evidence. This is not a new workflow stage and must not create extra user steps.
-- Review must compare the execution scope against the approved workflow scope. If `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`, review must return no-go and route to build or plan. A partial slice may be accepted as useful work, but it must not be approved as full workflow completion.
-- Review must compare implementation evidence against the original source requirements and `.loopx/workflows/<slug>/requirement-traceability.md`, not only against the generated plan. If the traceability matrix is missing, partial, or contradicted by code/tests, route to `review -> plan` or `review -> clarify` depending on whether the plan or requirements are wrong.
-- Code review findings should focus on real bugs, regressions, missing tests, broken contracts, security/data-integrity risks, and user-visible behavior gaps.
-- If code review finds blocking high or medium severity issues, return a no-go verdict and rollback guidance instead of approving completion.
-- If architecture-smell findings are only advisory, record them as warnings without blocking. Block only when module seams, testability, domain boundaries, duplicated rules, or plan architecture assumptions are materially wrong.
-- Route request-changes by problem type:
-  - implementation bugs, missing tests, small contract fixes: `review -> build`
-  - wrong plan, wrong architecture, unresolved execution inputs: `review -> plan`
-  - unclear product requirements or decision boundaries: `review -> clarify`
-- Do not route implementation-only fixes back to plan unless the plan itself is wrong.
-
-## Next Step Format
-
-Every no-go review result must end with a concrete next command block.
-
-For implementation fixes:
-
-Default implementation-fix handoff:
-
-```text
-Next:
-$build --from-review .loopx/workflows/<slug>/review-report.md
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-The review artifact is the direct rework contract for implementation fixes. `$build --from-review ...` must load the review findings first, while still using the approved PRD, test spec, previous `execution-record.md`, and workflow-local plan package as supporting context. Do not make the normal Codex-facing handoff require a separate bash `loopx approve ... --from review --to build` step.
+**2. Dispatch code reviewer subagent:**
 
-For CLI/runtime debugging only, the equivalent state transition is:
+Use the platform's native subagent mechanism when available and fill template at `code-reviewer.md`.
 
-```bash
-loopx build --from-review .loopx/workflows/<slug>/review-report.md
-```
+**Placeholders:**
+- `{DESCRIPTION}` - Brief summary of what you built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
 
-For plan fixes:
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
 
-```text
-Next:
-loopx approve <slug> --from review --to plan
-$plan <slug>
-```
-
-For clarify fixes:
+## Example
 
-```text
-Next:
-loopx approve <slug> --from review --to clarify
-$clarify <slug>
 ```
+[Just completed Task 2: Add verification function]
 
-For approval:
+You: Let me request code review before proceeding.
 
-```text
-Next:
-$archive <slug>
-```
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
 
-`$archive` consumes the pending `review -> done` completion transition before syncing specs. Do not ask the user to run a separate `loopx approve <slug> --from review --to done` command in the normal Codex-facing flow.
+[Dispatch code reviewer subagent]
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/loopx/plans/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
 
-For CLI/runtime debugging only, the equivalent explicit sequence is:
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
 
-```bash
-loopx approve <slug> --from review --to done
-loopx archive <slug>
+You: [Fix progress indicators]
+[Continue to Task 3]
 ```
 
-This syncs the approved `.loopx/changes/active/<change-id>/spec-delta.md` into long-lived `.loopx/specs/` files and moves the change folder under `.loopx/changes/archive/<change-id>/`.
-
-## Support Skill Review Lenses
+## Integration with Workflows
 
-Use loopx support skills as review lenses, not as implementation instructions:
+**Subagent Exec:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
 
-- `verify`: Evidence lens. Reject completion, passing, or review-ready claims that lack fresh command output and exit status.
-- `scope`: Completion lens. Reject full-completion claims when the execution record still declares remaining workflow scope or only a partial slice was implemented.
-- `tdd`: Behavior-change lens. Feature work and bug fixes should include failing-test or regression-test evidence unless the execution record explicitly explains why tests are not applicable.
-- `debug`: Failure-analysis lens. Fixes for bugs, test failures, build failures, and unexpected behavior should document root cause, not only symptoms or attempted patches.
-- `go-style`: Go diff lens. For `.go` changes, review happy-path structure, error handling, context usage, interface boundaries, naming, table tests, and `gofmt`/Go verification evidence.
-- `kratos`: Kratos diff lens. For Kratos/proto/service/biz/data/middleware/auth/config changes, review layer boundaries, generated-code flow, proto/package contracts, middleware/auth ordering, config compatibility, and project-native verification.
+**Exec:**
+- Review after each task or at natural checkpoints
+- Get feedback, apply, continue
 
-These lenses can produce review findings when the execution package violates them. Do not run new build work from `review`; request rollback or changes instead.
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
 
-## Must Not Decide Automatically
+## Red Flags
 
-- final completion without an explicit approval step
-- re-running build work inside the review surface
-- editing code or rerunning build from inside review
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
 
-## Notes
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
 
-- Review consumes structured outputs from the active loopx run. It should reject thin or placeholder-only evidence.
+See template at: review/code-reviewer.md

package/plugins/loopx/skills/review/code-reviewer.md

@@ -0,0 +1,168 @@
+# Code Reviewer Prompt Template
+
+Use this template when dispatching a code reviewer subagent.
+
+**Purpose:** Review completed work against requirements and code quality standards before it cascades into more work.
+
+```
+Native subagent:
+  description: "Review code changes"
+  prompt: |
+    You are a Senior Code Reviewer with expertise in software architecture,
+    design patterns, and best practices. Your job is to review completed work
+    against its plan or requirements and identify issues before they cascade.
+
+    ## What Was Implemented
+
+    {DESCRIPTION}
+
+    ## Requirements / Plan
+
+    {PLAN_OR_REQUIREMENTS}
+
+    ## Git Range to Review
+
+    **Base:** {BASE_SHA}
+    **Head:** {HEAD_SHA}
+
+    ```bash
+    git diff --stat {BASE_SHA}..{HEAD_SHA}
+    git diff {BASE_SHA}..{HEAD_SHA}
+    ```
+
+    ## What to Check
+
+    **Plan alignment:**
+    - Does the implementation match the plan / requirements?
+    - Are deviations justified improvements, or problematic departures?
+    - Is all planned functionality present?
+
+    **Code quality:**
+    - Clean separation of concerns?
+    - Proper error handling?
+    - Type safety where applicable?
+    - DRY without premature abstraction?
+    - Edge cases handled?
+
+    **Architecture:**
+    - Sound design decisions?
+    - Reasonable scalability and performance?
+    - Security concerns?
+    - Integrates cleanly with surrounding code?
+
+    **Testing:**
+    - Tests verify real behavior, not mocks?
+    - Edge cases covered?
+    - Integration tests where they matter?
+    - All tests passing?
+
+    **Production readiness:**
+    - Migration strategy if schema changed?
+    - Backward compatibility considered?
+    - Documentation complete?
+    - No obvious bugs?
+
+    ## Calibration
+
+    Categorize issues by actual severity. Not everything is Critical.
+    Acknowledge what was done well before listing issues — accurate praise
+    helps the implementer trust the rest of the feedback.
+
+    If you find significant deviations from the plan, flag them specifically
+    so the implementer can confirm whether the deviation was intentional.
+    If you find issues with the plan itself rather than the implementation,
+    say so.
+
+    ## Output Format
+
+    ### Strengths
+    [What's well done? Be specific.]
+
+    ### Issues
+
+    #### Critical (Must Fix)
+    [Bugs, security issues, data loss risks, broken functionality]
+
+    #### Important (Should Fix)
+    [Architecture problems, missing features, poor error handling, test gaps]
+
+    #### Minor (Nice to Have)
+    [Code style, optimization opportunities, documentation polish]
+
+    For each issue:
+    - File:line reference
+    - What's wrong
+    - Why it matters
+    - How to fix (if not obvious)
+
+    ### Recommendations
+    [Improvements for code quality, architecture, or process]
+
+    ### Assessment
+
+    **Ready to merge?** [Yes | No | With fixes]
+
+    **Reasoning:** [1-2 sentence technical assessment]
+
+    ## Critical Rules
+
+    **DO:**
+    - Categorize by actual severity
+    - Be specific (file:line, not vague)
+    - Explain WHY each issue matters
+    - Acknowledge strengths
+    - Give a clear verdict
+
+    **DON'T:**
+    - Say "looks good" without checking
+    - Mark nitpicks as Critical
+    - Give feedback on code you didn't actually read
+    - Be vague ("improve error handling")
+    - Avoid giving a clear verdict
+```
+
+**Placeholders:**
+- `{DESCRIPTION}` — brief summary of what was built
+- `{PLAN_OR_REQUIREMENTS}` — what it should do (plan file path, task text, or requirements)
+- `{BASE_SHA}` — starting commit
+- `{HEAD_SHA}` — ending commit
+
+**Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment
+
+## Example Output
+
+```
+### Strengths
+- Clean database schema with proper migrations (db.ts:15-42)
+- Comprehensive test coverage (18 tests, all edge cases)
+- Good error handling with fallbacks (summarizer.ts:85-92)
+
+### Issues
+
+#### Important
+1. **Missing help text in CLI wrapper**
+   - File: index-conversations:1-31
+   - Issue: No --help flag, users won't discover --concurrency
+   - Fix: Add --help case with usage examples
+
+2. **Date validation missing**
+   - File: search.ts:25-27
+   - Issue: Invalid dates silently return no results
+   - Fix: Validate ISO format, throw error with example
+
+#### Minor
+1. **Progress indicators**
+   - File: indexer.ts:130
+   - Issue: No "X of Y" counter for long operations
+   - Impact: Users don't know how long to wait
+
+### Recommendations
+- Add progress reporting for user experience
+- Consider config file for excluded projects (portability)
+
+### Assessment
+
+**Ready to merge: With fixes**
+
+**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
+```