Task types and filled artifacts

# TASK_SPEC
Type: environment-setup
Mode: General
Goal: Confirm that Claude Code opens the intended repository with understandable commands, settings, and a safe starting state.
Scope:
- CLI installation, authorization, and version.
- Repository README, scripts, and project settings.
- Git status and the first recovery checkpoint.
Non-goals:
- Editing application code.
- Relaxing permissions to bypass an unclear problem.
- Publishing secrets or taking irreversible actions.
Success:
- The repository and current state are identified.
- Run and verification commands are located in the repository.
- Unverified areas are marked Unknown.
Rules:
- Start with read-only inspection and `git status`.
- Never store credentials in files or prompts.
- Stop if the active directory is not the intended repository.

# TASK_SPEC
Type: feature
Mode: General
Goal: Turn a user need into a small end-to-end change with observable desired behavior and checkable acceptance.
Scope:
- One user flow and its entry points.
- Required UI, API, or domain changes plus focused tests.
- The documented public contract affected by the slice.
Non-goals:
- An unrequested redesign.
- General cleanup in neighboring modules.
- Business-rule changes outside the request.
Success:
- The new behavior is described through observable signals.
- Existing scenarios remain protected.
- Acceptance and verification are tied to the diff.
Rules:
- Separate goal, scope, constraints, and acceptance.
- Do not treat a ticket-named file as proven change location.
- Agree on the plan before editing.

# TASK_SPEC
Type: acceptance-verification
Mode: General
Goal: Make readiness conditions observable, measurable, and suitable for independent verification.
Scope:
- Functional and negative scenarios.
- Compatibility plus UI or API signals.
- Commands, expected results, and failure conditions.
Non-goals:
- Mandating a particular library.
- A vague “make it better” criterion.
- An automatic merge decision.
Success:
- Every criterion has a signal and a check.
- Behavior that must remain unchanged is named.
- Definition of done covers scope, diff, checks, and review.
Rules:
- Derive criteria from confirmed facts.
- Keep acceptance separate from the implementation plan.
- Mark an unperformed check Unknown.

# TASK_SPEC
Type: issue-intake
Mode: General
Goal: Separate the raw issue into problem, impact, evidence, requirements, assumptions, boundaries, and open questions.
Scope:
- Issue text, comments, labels, and attachments.
- Read-only investigation handoff.
- Non-goals, risks, and the next step.
Non-goals:
- Automatically accepting the proposed fix.
- Editing code during intake.
- Closing open questions with assumptions.
Success:
- The next engineer can recover context without a verbal briefing.
- Facts and hypotheses are separated.
- One concrete next step is named.
Rules:
- Do not treat a ticket-named file as a proven cause.
- Check the public contract separately.
- Keep Unknown explicit.

# TASK_SPEC
Type: implementation-plan
Mode: General
Goal: Turn confirmed findings into small ordered changes with risks, verification, a stop condition, and rollback.
Scope:
- Affected files and modules.
- Ordered implementation steps.
- Acceptance links and failure path.
Non-goals:
- Editing before approval.
- Expanding scope through cleanup.
- Planning unrelated features.
Success:
- The plan is self-contained for implementation.
- Every step has a check.
- Broad or risky steps have a stop condition.
Rules:
- Plan after investigation.
- Keep one logical intent per slice.
- Do not hide risk behind the word “refactor”.

# TASK_SPEC
Type: investigation-diagnosis
Mode: General
Goal: Separate symptoms from hypotheses, trace a flow, and return an evidence-backed finding or the next safe check.
Scope:
- One failure or runtime flow.
- Code, tests, configuration, logs, and reproduction steps.
- Confidence, unknowns, and next action.
Non-goals:
- Editing during discovery.
- Inferring a cause from a filename alone.
- A long transcript instead of a concise conclusion.
Success:
- Every conclusion has an evidence anchor.
- Hypotheses are not presented as facts.
- Unsafe actions are not launched automatically.
Rules:
- Stay read-only until separate approval.
- Remove secrets and personal data from logs.
- Incomplete evidence means Unknown.

# TASK_SPEC
Type: codebase-discovery
Mode: General
Goal: Create an evidence-backed map of the stack, modules, entry points, runtime flows, dependencies, and unknowns.
Scope:
- Top-level structure and manifests.
- Key modules, tests, and commands.
- One dependency or runtime slice.
Non-goals:
- Reading the entire repository sequentially.
- Refactoring discovered problems.
- Drawing conclusions from directory names alone.
Success:
- A new engineer knows where to find the logic.
- The map includes sources and confidence.
- Open questions remain distinct from facts.
Rules:
- Use a separate read-only session.
- Keep facts and assumptions separate.
- Do not change files while mapping.

# TASK_SPEC
Type: bugfix
Mode: General
Goal: Reproduce a defect, test the cause, make the smallest safe fix, and leave evidence that a reviewer can inspect.
Scope:
- One failure path.
- A regression case and an adjacent positive scenario.
- The diff, checks, and remaining-risk record.
Non-goals:
- Rewriting the entire error architecture.
- Feature work during the bugfix.
- Inventing test results.
Success:
- The defect is reproducible before the fix.
- A regression check protects the repaired scenario.
- External contract changes are explicit and approved.
Rules:
- Diagnose from facts before editing.
- Inspect the diff after every change.
- An Unknown cause is not permission for a broad patch.

# TASK_SPEC
Type: refactoring
Mode: General
Goal: Improve internal structure while preserving observable behavior, public APIs, side effects, and invariants.
Scope:
- One structural change.
- Dependent focused checks and diff review.
- An explicit rollback point.
Non-goals:
- New features or bug fixes.
- Dependency or framework upgrades.
- Data-format or contract changes.
Success:
- The diff has one structural purpose.
- Characterization and targeted checks show no unapproved behavior change.
- A rollback point is recorded.
Rules:
- Do not begin by editing.
- Work in one reviewable slice.
- Stop when public behavior changes.

# TASK_SPEC
Type: characterization
Mode: General
Goal: Build a safety net for a narrow flow by recording actual inputs, outputs, errors, and side effects before refactoring.
Scope:
- One bounded flow.
- Representative and edge-case inputs.
- Observed results and explicit unknowns.
Non-goals:
- Correcting surprising behavior.
- Replacing current behavior with preferred design.
- A broad test rewrite.
Success:
- A test or record reproduces current behavior.
- Unexpected results are called out.
- The behavior to protect before change is agreed.
Rules:
- Record observations, not assumed causes.
- Do not alter implementation while establishing the baseline.
- Mark everything unverified as Unknown.

# TASK_SPEC
Type: tests
Mode: General
Goal: Choose test levels and cases from risk instead of generating assertions disconnected from the contract.
Scope:
- Critical rules and boundary cases.
- Unit, integration, API, or E2E level as justified.
- Failure conditions and representative data.
Non-goals:
- Maximizing coverage for its own sake.
- Brittle E2E coverage for every branch.
- Changing production code without a separate task.
Success:
- Every important risk has a check.
- Assertions describe an observable result.
- Test data contains no secrets or personal data.
Rules:
- State acceptance before choosing tests.
- Do not trust a test that misses the required behavior.
- Mark unexecuted results Unknown.

# TASK_SPEC
Type: documentation
Mode: General
Goal: Turn confirmed system facts into concise documentation for a specific reader without inventing details.
Scope:
- One document or section.
- Actual commands, paths, and contracts.
- Diff review and practical example checks.
Non-goals:
- Rewriting all documentation.
- Adding unverified promises.
- Publishing secrets, personal data, or internal tokens.
Success:
- Each important claim has a source.
- Examples match observed behavior or are marked Unknown.
- The documentation diff is reviewable.
Rules:
- Define the reader and purpose first.
- Check documentation against code, configuration, and tests.
- Never present an illustrative snippet as production evidence.

# TASK_SPEC
Type: pr-slicing
Mode: General
Goal: Turn an approved plan into small logical parts that can be checked, reviewed, and reverted independently.
Scope:
- One intent per slice.
- A limited file set.
- Acceptance link, focused check, and rollback.
Non-goals:
- A big-bang pull request.
- Hidden cleanup.
- Mixing a feature, refactor, and dependency update.
Success:
- Every slice has a clear purpose.
- The order does not hide an unfinished contract.
- A reviewer can isolate a failure.
Rules:
- Decompose after plan approval.
- The first slice may be reproduction or evidence.
- Stop when the diff expands.

# TASK_SPEC
Type: handoff-recovery
Mode: General
Goal: Give a fresh reviewer enough state to reproduce evidence and continue a long task without guesswork.
Scope:
- Current diff and checkpoint.
- Done, checked, risky, and unknown items.
- One next action and a stop condition.
Non-goals:
- Transmitting secrets or the full transcript.
- Automatically continuing after handoff.
- Hiding failed checks.
Success:
- Another participant understands the state without a verbal handoff.
- Rollback and checkpoint are named.
- Unverified claims are marked.
Rules:
- Separate facts from next steps.
- Keep only the context needed to continue.
- Do not confuse session rewind with Git rollback.

# TASK_SPEC
Type: extensions-evaluation
Mode: General
Goal: Test an integration capability, permissions, lifecycle, and rollback in a narrow trial before sharing it with a team.
Scope:
- One capability and one bounded scenario.
- Origin, permissions, and authentication boundary.
- Log-only trial, verification, and kill switch.
Non-goals:
- Installing an unverified package for the team.
- Credentials in the repository.
- Blocking automation without evidence.
Success:
- The trial has a stated value signal.
- Side effects and data boundaries are understood.
- Disable and rollback are possible.
Rules:
- Start manually or in log-only mode.
- Grant the minimum permissions.
- Stop on prompt injection or unclear ownership.

# TASK_SPEC
Type: agent-orchestration
Mode: General
Goal: Split independent workstreams among roles with explicit ownership, output contracts, checkpoints, and a merge strategy.
Scope:
- Decomposition and dependency order.
- Scoped tools and context for each role.
- Handoff, merge strategy, and human checkpoint.
Non-goals:
- Parallelism for its own sake.
- Uncoordinated edits to one file.
- Automatic acceptance of agent output.
Success:
- Streams are independent or their dependencies are explicit.
- Every output has evidence and status.
- A person retains the merge or go/no-go decision.
Rules:
- First decide whether a subagent is needed.
- Delegate narrowly and limit tools.
- Stop on conflict or absent safety net.

# TASK_SPEC
Type: investigation-diagnosis
Mode: General
Goal: Classify a red job as test, build, environment, contract, or flaky and return an evidence-backed next action.
Scope:
- Job status and relevant sanitized output.
- Local reproducibility.
- Diagnosis, confidence, and safe next action.
Non-goals:
- An automatic production fix.
- Putting secrets in a prompt.
- Calling a failure flaky without checking it.
Success:
- The classification has a concrete evidence anchor.
- Logs are sanitized.
- The next action does not bypass approval.
Rules:
- Start with the first reliable signal.
- Keep CI status separate from root cause.
- Incomplete logs mean Unknown.

# TASK_SPEC
Type: ci-build
Mode: General
Goal: Describe a reproducible build and packaging workflow while separating technical signals from publish or deploy decisions.
Scope:
- Build command and clean environment.
- Package or container path plus smoke signal.
- Changelog, release notes, and human gate.
Non-goals:
- Production deployment.
- Publishing without approval.
- Hiding a failed build or incomplete smoke check.
Success:
- Input commands and output artifacts are defined.
- Smoke criteria are observable.
- The release boundary has an owner and rollback path.
Rules:
- Claude can analyze but does not replace the build.
- Use minimum permissions.
- Do not claim a passing build without output.

# TASK_SPEC
Type: quality-release
Mode: General
Goal: Make a blocking or advisory check transparent: what it checks, which evidence it returns, and when it stops delivery.
Scope:
- Signal, threshold, and status.
- Blocking or advisory policy.
- Owner, exception, and recovery path.
Non-goals:
- A gate added only for a metric.
- Automatic merge without human policy.
- Combining unrelated checks.
Success:
- A failure is understandable to another engineer.
- Evidence is retained.
- Rerun, rollback, or disable paths are known.
Rules:
- Start advisory when the signal is new.
- Do not hide flaky or environment failures.
- A person makes the final decision.

# TASK_SPEC
Type: risk-policy
Mode: General
Goal: Match risk classification, permissions, data boundaries, protected paths, and human approval to the proposed action.
Scope:
- Task classification.
- Allowed tools, paths, and data.
- Owner, approval, audit trail, and stop condition.
Non-goals:
- Bypassing a permission prompt.
- Sending secrets or personal data into context.
- Autonomous production deployment.
Success:
- The capability envelope fits the risk.
- Protected paths have enforcement.
- The GO or HOLD decision has evidence and an owner.
Rules:
- Use least privilege by default.
- Sanitize sensitive data before sharing.
- Keep irreversible actions with a person.

# TASK_SPEC
Type: capstone
Mode: General
Goal: Constrain a final project to one core flow and connect problem, user, value proposition, specification, release slice, milestones, demo, defense, evidence, AI-native career proof, and a bounded job-search workflow.
Scope:
- Problem, primary user, job to be done, and value proposition.
- One core flow, success metric, and release slice.
- Specification, repository baseline, reviewer checklist, and evaluation evidence.
- Controlled AI-assisted implementation with bounded diffs and human checkpoints.
- Implementation sprint slices, verification, demo quality gates, readiness, and defense handoff.
- Submission package, reproducibility audit, defense narrative, and rubric.
- Mentor findings, remediation backlog, and portfolio packaging after review.
- AI-native positioning, proof-of-work bank, career narrative, resume/GitHub/LinkedIn consistency, and portfolio defense.
- Target role strategy, vacancy fit/gap analysis, truthful application tailoring, application tracker/career workspace, and an assessment feedback loop.
Non-goals:
- Demonstrating the entire product.
- Inventing metrics, research, or screenshots.
- Production deployment, scale claims, or scope expansion during a demo.
- Claiming an executed sprint, demo, defense, mentor review, remediation, portfolio publication, employment, or hiring outcome without evidence.
- Real applications, interviews, assessments, recruiter feedback, mass outreach, impersonation, or hiring claims without evidence.
- Treating a capstone template as proof of completed work.
Success:
- Value, user job, and evaluation criteria are defined before coding.
- The release slice has scope, non-goals, a metric, and an evidence plan.
- Small diffs, sprint checkpoints, and stop conditions are recorded.
- The demo has blocking and advisory gates plus a fallback.
- The submission has a bounded entry point, inputs, expected signal, and known limits.
- Reproducibility, defense narrative, and rubric separate facts, assumptions, and Unknowns.
- Mentor findings become a traceable remediation backlog rather than an unverified claim.
- Career materials separate personal contribution, AI assistance, verified evidence, and Unknowns.
- Job-search records have traceable sources, privacy-safe fields, explicit Unknowns, and bounded next actions; no record attributes a hiring outcome.
Rules:
- Start with one user and one verified slice.
- Record assumptions, Unknowns, and limitations.
- Limit every AI-assisted iteration to allowed paths and diff review.
- Choose HOLD on scope drift, a missing oracle, or an unexplained change.
- Never present a documented example as production readiness, deployment, validation, or approval.
- Do not call an audit, rubric application, mentor review, or remediation complete without evidence.
- Do not turn AI-assisted output into a personal-work claim without traceable contribution and verification.
- Tailoring may use only verified evidence; require human review before external use, and mark unsupported application, interview, or feedback claims Unknown.

# TASK_SPEC
Type: codebase-discovery
Mode: General
Goal: Describe current architecture, technical-debt signals, critical flows, and change risk before editing anything.
Scope:
- Observed behavior of one legacy flow.
- Modules, dependencies, and static signals.
- Business criticality, change risk, and unknowns.
Non-goals:
- An immediate refactor.
- An invented target architecture.
- A conclusion from one smell without evidence.
Success:
- Current state is separate from desired state.
- The risk map includes evidence and confidence.
- The next action is bounded.
Rules:
- Begin with read-only discovery.
- Keep business criticality distinct from change risk.
- Expose Unknown blockers explicitly.

# TASK_SPEC
Type: modernization
Mode: Modernization
Goal: Reduce technical risk in one legacy module without changing its external contract or business meaning.
Scope:
- One bounded module or business flow.
- One structural change through a confirmed seam.
- Characterization, focused checks, and rollback.
Non-goals:
- A big-bang rewrite.
- Public API, business-rule, or data-format changes.
- Framework or dependency upgrades and new features.
Success:
- One reviewable slice has a limited diff.
- Inputs, outputs, errors, side effects, and invariants remain compatible.
- Checks are executed or marked Unknown.
Rules:
- Start with `MODERNIZATION_BASELINE.md` and `RISK_MAP.md`.
- Give every step non-goals and a stop condition.
- Stop on an unconfirmed contract change.

# TASK_SPEC
Type: migration
Mode: Migration
Goal: Prepare a bounded transition to a defined target state and proceed only when branch, rollback, and validation gates are available.
Scope:
- Source and target runtime, framework, and dependency constraints.
- One pilot slice in a branch or worktree.
- Rollback for code, configuration, data or state, and traffic.
- Behavior-parity cases and validation evidence.
- Maps for code, dependency, schema, data, configuration, infrastructure, and operations.
- Official documentation and repository files.
Non-goals:
- Refactoring BillingService.
- Uncontrolled database or schema change.
- New features, full rollout, or production deployment.
- Storing secret values in specifications, logs, or evidence.
- Version changes or execution before discovery, approval, and recovery planning.
Success:
- Known, Assumption, and Unknown are separated.
- Pilot slice, branch or worktree, owner, and entry or exit gates are defined.
- Rollback is a verifiable prerequisite and stateful limitations are explicit.
- Behavior-parity dimensions, evidence anchors, and discrepancy decisions are defined.
- Migration types, data or configuration sequencing, validation, and recovery paths are described; pre-execution outcome remains Unknown.
Rules:
- Use official documentation and repository files as the source of truth.
- Give every conclusion a documentation section or file path.
- Do not propose edits, builds, version changes, or rollout without request and approval.
- Start with discovery, changelog research, dependency graph, compatibility matrix, and migration-type map.
- Do not start the pilot without a rollback trigger, owner, checkpoint, and post-rollback check.
- Choose HOLD for an unexplained discrepancy, irreversible state, or missing oracle.