Task Implementation

Auto-loaded

These files are automatically read at the start of implementation:

1. docs/engineering/STACK.md - Tech stack and available scripts
2. docs/engineering/CODE_STANDARDS.md - Development philosophy and quality standards
3. docs/engineering/WORKFLOW.md - Git workflow and commit guidelines
4. docs/engineering/TESTING.md - Testing philosophy, three pillars, and patterns

Optional Context (read when needed)

• docs/PRD.md - Product requirements for business context
• docs/architecture/*.md - Architecture decisions and patterns
• docs/use-cases/*.md - User scenarios and edge cases

Complexity Guard

Before starting implementation, assess task complexity:

• 3+ new models OR 10+ files to create/modify OR architectural decisions needed → Suggest the user plan first with task-planner:

⚠️ Esta tarefa é complexa (3+ modelos / 10+ arquivos / decisões arquiteturais). Recomendo planejar primeiro com: "Planeje [descrição]" usando a skill task-planner.

Do NOT invoke task-planner directly — inform the user and let them decide.

2. Pre-Implementation Setup

Step 1: Understand the Task

Before writing code:

1. Read the full task definition from docs/tasks/
2. Understand all acceptance criteria
3. Identify dependencies on other tasks
4. Check current progress in docs/progress/<epic-slug>.md

If task has dependencies marked as TODO or IN_PROGRESS:

⚠️ Task [ID] depends on [DEP-ID] which is not complete. Do you want to implement the dependency first?

Step 2: Create Semantic Branch

Create a branch following naming convention:

# Single task
git checkout -b feat/<epic-slug>-<task-description>

# Examples
git checkout -b feat/cti-tracing-interface
git checkout -b fix/sp-session-restore
git checkout -b refactor/jp-job-middleware

Branch types from WORKFLOW.md:

• feat/ - New feature
• fix/ - Bug fix
• refactor/ - Code refactoring
• chore/ - Tooling, config
• docs/ - Documentation only
• test/ - Test additions

Step 3: Update Progress Status (CRITICAL)

This step is MANDATORY and must happen BEFORE writing any code.

Update docs/progress/<epic-slug>.md immediately:

### [TASK-ID] Task Name

**Status**: `IN_PROGRESS`
**Started**: YYYY-MM-DD
**Notes**: Starting implementation

⚠️ DO NOT skip or defer this step. Progress tracking provides:

• Visibility into current work
• Recovery point if implementation fails
• Accurate timestamps for reporting

3. Implementation Workflow

Development Loop

For each acceptance criterion:

1. Implement - Write code following CODE_STANDARDS.md
2. Test - Run tests if applicable
3. Commit - Semantic commit for the change

Semantic Commits

Follow commit format from WORKFLOW.md:

<type>(<scope>): <short description>

[optional body]

Types: feat, fix, refactor, chore, docs, test, style, perf

Commit by functional activity, not by file.

# ✅ Good
git commit -m "feat(tracing): add correlation ID interface"

# ❌ Bad
git commit -m "update TracingInterface.php"

Code Quality Standards

From CODE_STANDARDS.md:

• No DDD - No over-engineering
• Pragmatic SOLID - Apply for clarity, not layers
• Testable - Business logic is unit-testable
• Extensible - Easy to add features

4. Quality Gates

All gates MUST pass before completing a task. See docs/engineering/QUALITY_GATES.md for the full specification.

Execute gates in order: Lint → Test → i18n → Security. See the canonical doc for stack-specific commands, three-pillar requirements, and failure handling.

See references/gate-checklist.md for detailed validation steps specific to this skill.

5. Task Completion

Update Progress Tracking

When all acceptance criteria are met and gates pass:

Step 1: Update Epic Progress File

Update docs/progress/<epic-slug>.md:

### [TASK-ID] Task Name

**Status**: `DONE`
**Started**: YYYY-MM-DD
**Completed**: YYYY-MM-DD
**Commits**:

- `abc1234` feat(scope): description
- `def5678` test(scope): add tests
  **Notes**: Implementation details or decisions made

Step 2: Update Progress README (MANDATORY)

Update docs/progress/README.md with:

1. Epic Progress table: Update counts (TODO → Done) and percentage
2. Recent Completions table: Add completed task at the top
3. Current Focus: Update if epic changed or task in progress changed
4. Total row: Recalculate totals across all epics
5. Last Updated date: Update to current date

⚠️ The README.md is a dashboard derived from epic progress files. It MUST be updated after every task completion to maintain accuracy.

Update Related Documentation

If implementation affects documentation:

• Update relevant docs/architecture/*.md
• Update README.md if public API changed
• Update config file comments if new options added

6. Pull Request

Ask Before Opening

Always ask the user:

✅ Task [ID] concluída com sucesso. Deseja que eu abra um Pull Request?

If User Confirms

Create PR with semantic title and detailed description:

Title Format:

<type>: <short description>

Examples: