# Agile Refinement

> Validates planning artifacts and reviews code for quality, consistency, and completeness. Use to lint planning documents (cross-references, dependencies, format) or to review changed code (security, coherence, scope, quality).

- Skill: `djalmajr/agile-refinement` (Agent Skill)
- Install (CLI): `npx skillmds@latest add djalmajr/agile-refinement`
- Raw SKILL.md: https://api.skillmd.com/api/skills/djalmajr/agile-refinement/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: djalmajr (https://skillmd.com/u/djalmajr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/djalmajr/agile-refinement

---


# Refinement

Use this skill to validate planning artifacts and review code quality. It operates in two modes: planning lint and code review.

Initial context received via slash: $ARGUMENTS

If `$ARGUMENTS` is filled (e.g., file path, branch, "planning", "code"), use as starting point to determine mode.
If empty, ask the user what they want to validate: planning artifacts or code changes.

## Language

Write any report output in the user's language. Apply correct grammar and any required diacritics or script-specific characters. If the user's language is unclear, ask before generating output.

## Project root

This skill writes artifacts at paths relative to the **project root** (the repo where the work happens), not the agent's current working directory.

- If invoked from inside the project, use the relative paths shown in this skill.
- If invoked from another directory (e.g., a sibling repo, or when the project lives elsewhere), prepend `<project-root>/` to every artifact path.
- When the project root is ambiguous, confirm with the user via the harness question tool before writing.

## Prompting

Follow the project-wide convention in `CLAUDE.md` / `AGENTS.md` ("Skill Prompting Conventions"). Use the harness's structured-question tool — `AskUserQuestion` (Claude Code), `ask_user_question` (Codex), or `question` (OpenCode) — for the decision points below. Use free-form text only where a path/name/value cannot be enumerated.

| Decision point | Why structured | Suggested options |
|---|---|---|
| Target | Branches the workflow | Planning artifact · Code · Both |
| Depth | Affects review effort | Lint-only · Full review · Security focus |

Free-form prompts (no structured tool):

- File paths to review
- Specific concerns

No-pause mode: if the user has explicitly disabled mid-skill clarification, convert every structured prompt into an entry under *Open questions* (or equivalent) and proceed without blocking.

## Objective

- Validate planning artifacts for consistency, completeness, and correctness
- Review code changes for security, coherence, scope, and quality
- Catch issues before they become problems in execution
- Provide actionable, specific feedback — not generic observations

## When to use

- Before starting implementation — lint the planning artifacts
- Before committing code — review the diff
- When opening a pull request — quality gate
- When reviewing AI-generated code — human-equivalent review
- Periodically — check for stale content, broken cross-references, or orphaned artifacts
- When merging or completing an epic — validate all pieces fit together

## When NOT to use

- Creating planning artifacts — use `/agile-intake`, `/agile-epic`, `/agile-story`, `/agile-roadmap`
- Decomposing work into stories — use `/agile-epic` (which now handles decomposition)
- Tracking delivery progress — use `/agile-status`
- Planning a sprint — use `/agile-sprint`

## Mode 1: Planning Lint

Validates planning artifacts against the following checks:

### Cross-references
- [ ] Origin fields point to existing files
- [ ] Referenced epics, stories, and tasks exist
- [ ] File paths in cross-references are correct and files are present

### Dependencies
- [ ] Declared dependencies between stories/tasks exist
- [ ] No circular dependencies
- [ ] Dependency order is consistent with the roadmap/epic sequence

### Completeness
- [ ] Required sections are present (Context, Files, Detail, Tasks, Verification)
- [ ] No empty required fields
- [ ] Acceptance criteria are defined and verifiable
- [ ] Tasks are specific and actionable (not vague)

### Product traceability
- [ ] UI-heavy epics/stories reference prototype routes/screens when prototypes exist
- [ ] Domain behavior references `business/*.md` rule IDs/files when business rules exist
- [ ] Prototypes do not carry internal implementation or business-rule explanations as visible product copy
- [ ] Business rules discovered during prototype review were captured outside the prototype
- [ ] No raw secrets, provider keys, tokens, or credentials appear in planning artifacts

### Consistency
- [ ] Sizing is consistent across related artifacts (stories within an epic)
- [ ] Status fields are up to date
- [ ] Naming conventions match across files

### Format
- [ ] File naming follows convention (`00-overview.md`, `NN-story-name.md`)
- [ ] Folder structure follows convention (`planning/<initiative>/epics/NN-<epic>/`)
- [ ] Templates are properly filled (no leftover placeholder text)

### Scope conflicts
- [ ] No overlapping scope between stories in the same epic
- [ ] Out-of-scope items are not referenced as tasks

### Stale content
- [ ] No artifacts with all tasks completed but status still "in progress"
- [ ] No referenced files that have been deleted or moved
- [ ] No plans older than 30 days with incomplete tasks and no recent daily

### Process

1. Identify the scope: a single file, an epic folder, or the entire `planning/` tree.
2. Read all artifacts in scope.
3. Run each check category above.
4. Produce an inline report grouped by category with specific issues and locations.

## Mode 2: Code Review

Reviews changed code applying the checklist from `~/.agents/rules/code-review.md`:

### Security
- [ ] Inputs validated and sanitized
- [ ] No SQL injection, XSS, command injection, or SSRF
- [ ] No hardcoded secrets
- [ ] Authentication and authorization correct when applicable
- [ ] Sensitive data not exposed in logs or responses

### Project Coherence
- [ ] Follows repository patterns and conventions
- [ ] Uses existing components, utilities, and helpers
- [ ] Did not reinvent the wheel
- [ ] Naming consistent with codebase
- [ ] Imports follow project conventions

### Over-engineering
- [ ] No premature abstractions
- [ ] No error handling for impossible scenarios
- [ ] No generalization for hypothetical requirements

### Scope
- [ ] Code does only what was requested
- [ ] No refactoring of unrelated code
- [ ] No additional features not requested

### Quality
- [ ] Tests cover acceptance scenarios
- [ ] Code readable without explanatory comments
- [ ] Small functions with single responsibility
- [ ] No logic duplication
- [ ] Errors handled at system boundaries

### Completeness
- [ ] Lint passes
- [ ] Typecheck passes
- [ ] Tests pass
- [ ] Diff read in full

### Process

1. Identify the scope: branch, files, or working tree changes.
2. Read the complete diff before issuing any output.
3. Apply each check category.
4. Produce an inline report grouped by category.
5. Highlight red flags that justify immediate rejection.

## Output

This skill does NOT produce a saved artifact. It produces an inline report with:
- Issues grouped by category
- Severity: red flag (reject), warning (fix before proceeding), info (consider)
- Specific file and line references where applicable
- Actionable suggestions for each issue

## Rules

- Read everything in scope before producing any output.
- Be specific. "Code looks bad" is not actionable. "Replace `RateLimitError` with `HttpError` on line 42 of `src/middleware/rate-limit.ts`" is.
- AI code review does not replace human code review. This is an additional gate.
- Planning lint can be run at any time — it's a health check, not a ceremony.
- Never produce vague, generic feedback. Every issue must be verifiable.

## Relationship with the flow

```mermaid
flowchart LR
    A["/agile-epic"] --> B["/agile-refinement<br>(planning lint)"]
    C["/agile-story"] --> D[execution]
    D --> E["/agile-refinement<br>(code review)"]
    E --> F["/agile-status"]
```

This skill validates artifacts and code at any point in the flow. For creating planning artifacts, use `/agile-epic` or `/agile-story`. For tracking delivery, use `/agile-status`.