1660 Status 1b5d94e7

# Status Command

The `status` command validates whether growth loop requirements have been implemented in your codebase, using AST parsing to verify that required files, functions, and patterns are present.

## Prerequisites

Before running `status`, you need:

- A `skene-context/growth-loops/` directory containing one or more growth loop JSON files. These are generated by the `build` command. See [Build](build.md) for details.
- For the `--find-alternatives` flag: an API key configured for a cloud LLM provider (OpenAI, Gemini, Anthropic) or a local LLM server running. See [configuration](configuration.md) for setup instructions.

## Basic usage

Check the implementation status of all growth loops in the current project:

```bash
uvx skene-growth status
```

The command auto-detects `skene-context/growth-loops/` relative to the current directory and validates every growth loop JSON file found there.

Specify a different project root:

```bash
uvx skene-growth status ./my-project
```

Point to a specific context directory:

```bash
uvx skene-growth status --context ./my-project/skene-context
```

Use LLM-powered semantic matching to find alternative implementations for missing requirements:

```bash
uvx skene-growth status --find-alternatives --api-key "your-key"
```

## Flag reference

| Flag | Short | Description |
|------|-------|-------------|
| `--context PATH` | `-c` | Path to `skene-context` directory. Auto-detected from `<PATH>/skene-context/` or `./skene-context/` if not specified. |
| `--find-alternatives` | | Use LLM to search for existing functions that might fulfill missing requirements. Requires an API key. |
| `--api-key TEXT` | | API key for LLM provider (or `SKENE_API_KEY` env var). Required when `--find-alternatives` is set. |
| `--provider TEXT` | `-p` | LLM provider: `openai`, `gemini`, `anthropic`, `ollama` (uses config if not provided) |
| `--model TEXT` | `-m` | LLM model name (uses provider default if not provided) |

## How it works

The status command follows a three-step pipeline:

### Step 1: Locate growth loop definitions

The command searches for growth loop JSON files in `<context>/growth-loops/`. If `--context` is not provided, it auto-detects the context directory by checking:

1. `<PATH>/skene-context/` (where `PATH` is the positional argument, defaulting to `.`)
2. `./skene-context/`

If no `growth-loops/` directory is found, the command exits with an error.

### Step 2: Validate requirements

Each growth loop JSON defines requirements in two categories:

**File requirements** — The command checks that each required file exists and runs verification checks against it:

- `contains` — file contains a literal substring
- `contains_regex` — file matches a regular expression
- `function_exists` — a function with the given name exists (Python AST parsing)
- `class_exists` — a class with the given name exists (Python AST parsing)
- `import_exists` — an import matching the given name exists (Python AST parsing)

**Function requirements** — The command checks that each required function exists in the specified file, using Python AST parsing. If an expected signature is provided, it also validates that the actual signature matches.

### Step 3: Display validation report

The command outputs a summary showing:

- Total loops validated and how many are complete
- Per-loop breakdown with pass/fail status for every file and function requirement
- Detailed failure reasons (file not found, function missing, signature mismatch)

A loop is marked **COMPLETE** when all its file and function requirements pass. Otherwise it is marked **INCOMPLETE** with a table showing which checks failed.

## Finding alternative implementations

When `--find-alternatives` is enabled, the command extracts all function definitions from the project using AST parsing, then sends missing requirements to the LLM for semantic matching. This helps discover:

- Functions that already fulfill a requirement but have a different name
- Existing implementations in unexpected file locations
- Partial implementations that could be adapted

Alternative matches are displayed below the validation table with a confidence score (only matches above 60% confidence are shown).

```bash
uvx skene-growth status --find-alternatives
```

The LLM configuration is loaded from your config file and can be overridden with `--api-key`, `--provider`, and `--model`.

## Example output

```
Project root: /path/to/project
Context dir:  /path/to/project/skene-context
Loops dir:    /path/to/project/skene-context/growth-loops

Validating Share Flag...
  File requirement met: src/components/ShareButton.tsx...
  Function requirement met: handleShare...
Loop complete: Share Flag...

╭── Growth Loop Validation  —  1/2 loops complete ──╮
╰────────────────────────────────────────────────────╯

Share Flag (share_flag)  COMPLETE (3/3 checks, 12ms)

   ✅ GROWTH LOOP COMPLETE: Share Flag

Onboarding Flow (onboarding_flow)  INCOMPLETE (1/3 checks, 8ms)
 ✅  src/onboarding/welcome.py   Exists   OK
 ❌  src/onboarding/progress.py  Missing  File not found
 ❌  track_progress               src/onboarding/progress.py  Missing

1 loop(s) have unmet requirements.
```

## Next steps

- [Build](build.md) -- Generate growth loop definitions that the status command validates
- [Chat](chat.md) -- Use the interactive terminal chat for ad-hoc growth analysis
- [Configuration](configuration.md) -- Set up persistent config for LLM settings used by `--find-alternatives`
- [CLI Reference](../reference/cli.md) -- Full reference for all commands and flags