/spec-authoring

Name

spec-authoring

Description

Use this skill to propose changes via the Spec PR process. It uses the Gemini CLI to generate high-quality draft specifications and to analyze PR feedback, accelerating the spec-driven development workflow. Triggers include "create spec" or "propose change".

# Spec Authoring Skill

## Purpose

To manage the creation and refinement of feature specifications using a powerful, AI-assisted workflow. This skill leverages the **Gemini CLI** to accelerate the spec-driven development process by:
1.  **Generating Drafts**: Automatically creates high-quality, multi-file draft proposals for new features.
2.  **Analyzing Feedback**: Synthesizes review comments from Pull Requests into an actionable summary of recommended changes.

This approach allows developers and product managers to move from idea to an approved, implementation-ready specification with greater speed and clarity.

## When to Use

Use this skill in the following situations:

- Proposing a new feature or significant change.
- Generating a first draft of a specification for review.
- Processing and incorporating feedback from a Spec PR.

## Prerequisites

- Project initialized with AgenticDev structure (`docs/specs/` and `docs/changes/` directories exist).
- GitHub repository set up.
- `gh` CLI tool installed and authenticated.
- `gemini` CLI tool installed and authenticated.

## Spec PR Philosophy

**Specs as Code**: All specification changes follow the same rigor as code changes—proposed via branches, reviewed via PRs, and merged upon approval. This skill supercharges that philosophy with AI.

---

## The `propose` Command

### Purpose

Generate a comprehensive, multi-file draft proposal for a new feature from a single command.

### Workflow

#### Step 1: Define the Proposal Name

Choose a clear, descriptive name for your feature, such as "User Authentication System" or "Real-time Notifications".

#### Step 2: Run the Helper Script

Execute the script to generate the draft proposal:
```bash
bash scripts/spec-authoring.sh propose "Feature Name"
```

The script will:
1.  Create a new directory in `docs/changes/feature-name/`.
2.  Make three parallel calls to the **Gemini CLI** to generate drafts for `proposal.md`, `spec-delta.md`, and `tasks.md`.
    - **`proposal.md`**: A high-level overview with problem statement, proposed solution, and success criteria.
    - **`spec-delta.md`**: A detailed technical specification with requirements and design decisions.
    - **`tasks.md`**: A preliminary breakdown of implementation tasks.
3.  Save the AI-generated content into these files.

#### Step 3: Review and Refine the Drafts

The script provides you with a complete, context-aware first draft of your entire proposal. Your next step is to review and refine these documents to ensure they align with your vision before opening a Spec PR.

---

## The `update` Command

### Purpose

Intelligently process feedback from a Spec PR by using AI to analyze review comments and generate a summarized action plan.

### Workflow

#### Step 1: Identify the PR Number

Determine which Spec PR you need to update.

#### Step 2: Run the Feedback Analysis Script

Execute the script with the PR number:
```bash
bash scripts/spec-authoring.sh update PR_NUMBER
```

This command will:
1.  Find the local files associated with the PR's branch.
2.  Fetch all review comments from the PR.
3.  Send the full content of your spec files and all the comments to the **Gemini CLI**.
4.  Ask the AI to act as a reviewer and provide a summarized list of recommended changes for each file.

#### Step 3: Address the Synthesized Feedback

The script will output a clear, actionable plan that synthesizes all the reviewer feedback. Use this analysis to efficiently update your proposal files, address the comments, and push your changes for re-review.

---

## Error Handling

### Gemini CLI Issues

**Symptom**: The script fails during the `propose` or `update` commands with an error related to the `gemini` command.
**Solution**:
- Ensure the `gemini` CLI is installed and in your system's PATH.
- Verify you are authenticated (`gemini auth`).
- Check for Gemini API outages or network issues.

### Proposal Directory Already Exists

**Symptom**: The `propose` command reports that the directory already exists.
**Solution**: Choose a different name for your proposal or work with the existing one.

### Could Not Find Proposal Directory

**Symptom**: The `update` command cannot find the local files for the PR.
**Solution**: Ensure you have the correct PR branch checked out and that the local directory in `docs/changes/` matches the branch name.

## Notes

- **AI-Assisted Workflow**: This skill is designed to be a powerful assistant. It generates high-quality drafts and analyzes feedback, but the final strategic decisions and refinements are yours to make.
- **Speed and Quality**: By automating the initial drafting and feedback synthesis, this skill allows you to focus on the high-value work of design, review, and alignment.
- **Iterative Process**: Use the `propose` command to start, and the `update` command to iterate based on team feedback, creating a rapid and efficient spec development cycle.