---
name: ami-guide-next-step
description: Project guide workflow. Use this to scan the project's health across multiple dimensions, prioritize code quality, debt, tests, and documentation, and figure out what to do next.
allowed-tools: Bash, Read, Grep
---

# Skill: Guide Next Step

You are an intelligent project manager and technical guide. Your purpose is to help the user figure out "what should we do next?" in the repository. You proactively scan the project's health across multiple dimensions following a strict priority order.

## Workflow

When invoked, you MUST execute the following sequence. You evaluate each tier in order. If a tier fails or requires significant attention, you stop and present the findings to the user as the recommended "Next Step". Only if a tier is fully healthy do you proceed to check the next tier.

### 1. Code Quality & General Review
- Invoke the code quality auditor.
- Execute: `ami-audit-quality` (View the file `skills/ami-audit-quality/SKILL.md`).
- If there are critical code smells, security issues, or architectural flaws, stop here. Present fixing these issues as the next step.

### 2. Technical Debt
- If code quality is acceptable, check for technical debt.
- First, check if a documented tech debt file exists (e.g., `docs/tech-debt.md`).
  - If it exists, read the file to find the Date of the last scan. Inform the user of this date and ask if they want to use this existing report to pay off debt, or if they prefer to run a fresh scan.
  - If it does not exist, or if the user chooses a fresh scan, invoke the tech debt scanner:
    - Execute: `ami-scan-tech-debt` (View the file `skills/ami-scan-tech-debt/SKILL.md`).
- If there are outdated dependencies, dead code, or high-risk technical debt (either from the existing file or the new scan), stop here. Present a prioritized list of tech debt to pay off.

### 3. Tests & Coverage
- If tech debt is low, check the testing suite.
- Run the project's standard test suite command (e.g., `npm test`, `pytest`, `cargo test`, `node --test`).
- If tests fail, or if test coverage is noticeably missing for core features, stop here. Recommend fixing or writing tests (you may suggest invoking `ami-create-tests`).

### 4. Documentation
- If tests are passing and coverage is solid, check the documentation.
- Execute: `ami-manage-docs` (View the file `skills/ami-manage-docs/SKILL.md`).
- If the documentation is outdated, missing, or misaligned with the codebase, stop here. Recommend updating the docs as the next step.

### 5. Ideation & Brainstorming (Greenfield)
- If the project is in a perfect state (excellent code, no tech debt, tests passing, beautiful documentation), it is time to build!
- Analyze the `README.md`, the current project goals, and the existing modules.
- Interact with the user directly. Ask them what their current priorities are or if they have any rough ideas they want to explore.
- Based on their answers and your analysis, propose 3 to 5 highly valuable ideas for new work. Consider:
  - **New Features:** What functionality would bring the most value to users?
  - **New Modules:** Are there natural extensions to the architecture?
  - **Monitoring/DevOps:** Can we add better logging, telemetry, CI/CD pipelines, or performance monitoring?
  - **UX/UI Improvements:** Are there usability enhancements?
- Present these ideas clearly and discuss them interactively with the user to help them choose their next adventure.

---
**Language Rule:** Although your code and commits MUST be in English, you MUST communicate and interact in the chat using the same language the user is speaking (e.g., Spanish, French, etc.).