# Ss Ci Review

> Use when setting up CI gates, reviewing pull requests, interpreting verification failures, or adding Supersigil checks to automated pipelines. Activates on CI configuration, PR review workflows, and verification output triage.

- **Type:** Skill
- **Install:** `agentstack add skill-jonisavo-supersigil-ss-ci-review`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jonisavo](https://agentstack.voostack.com/s/jonisavo)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [jonisavo](https://github.com/jonisavo)
- **Source:** https://github.com/jonisavo/supersigil/tree/main/.agents/skills/ss-ci-review
- **Website:** https://supersigil.org

## Install

```sh
agentstack add skill-jonisavo-supersigil-ss-ci-review
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# CI and Review

Use this skill when the goal is to integrate Supersigil verification into
CI pipelines, review pull requests against spec coverage, or interpret
verification output in automated contexts.

## Current Contract

```bash
supersigil verify [--format terminal|json|markdown]
supersigil affected --since  [--format json]
supersigil status [] [--format json]
supersigil plan [] [--format json]
supersigil verify
```

## CI Pipeline Integration

### Basic Verification Gate

Add `supersigil verify` as a CI step. It exits non-zero when error-level
findings exist, making it a natural gate:

```yaml
# GitHub Actions example
- name: Verify specs
  run: supersigil verify --format terminal
```

### PR-Scoped Verification

Use `supersigil affected --since` to scope verification to documents
affected by the PR's changes:

```bash
# Find docs affected by changes in this PR
supersigil affected --since origin/main --format json
```

This returns documents whose `TrackedFiles` globs match changed files.
Use it to:
- Run targeted `supersigil status ` on each affected doc.
- Flag PRs that change tracked source files without updating specs.
- Detect stale specs before they reach the main branch.

### Structured Output for Annotations

Use `--format json` for machine-readable output that can drive GitHub
annotations, GitLab code quality reports, or custom dashboards:

```bash
supersigil verify --format json
```

The JSON output includes finding severity, affected document IDs, and
human-readable messages suitable for inline PR comments.

## PR Review Workflow

When reviewing a PR against Supersigil specs:

1. Run `supersigil affected --since origin/main` to identify which
   spec documents are touched by the change.

2. For each affected document, run `supersigil status ` to check
   current health: coverage, staleness, and status consistency.

3. Run `supersigil verify` to get the full finding set. Focus on:
   - New error-level findings introduced by the PR.
   - Coverage gaps: criteria without `VerifiedBy` evidence.
   - Stale tracked files: source changes not reflected in specs.
   - Status inconsistencies: tasks marked done but sibling docs
     not promoted.

4. Check that new code includes appropriate `supersigil: {tag}`
   comments or that `VerifiedBy` file-glob paths cover new test files.

5. If the PR introduces new behavior without spec coverage, flag it.
   New criteria should exist before or alongside the implementation,
   not after.

## Interpreting Findings

Supersigil has two layers of errors:

**Graph-build errors** (broken refs, cycles, duplicate IDs) are always
fatal. They prevent the graph from loading and cause `verify` to exit
non-zero regardless of document status. These are not affected by draft
gating or severity configuration.

**Verification findings** have configurable severity and are affected
by document status:

| Finding type | Default severity (non-draft) | CI action |
|--------------|------------------------------|-----------|
| Missing verification evidence | error | Block merge |
| Missing test files | error | Block merge |
| Status inconsistency | warning | Review required |
| Stale tracked files | warning | Review required |
| Orphan test tag | warning | Review required |
| Orphan decision | warning | Review required |

**Draft gating:** When a document is `status: draft`, all its
verification findings are unconditionally downgraded to `info`.
This means draft documents will not block CI even if they have
coverage gaps or status inconsistencies. Only graph-build errors
(broken refs, cycles, duplicates) remain fatal on draft documents.

## Coverage Reporting

Use `supersigil plan` to generate a coverage report showing outstanding
criteria and pending tasks:

```bash
supersigil plan --format json
```

This can feed into a coverage dashboard or be included as a PR comment
summarizing what work remains for a feature.

## Failure Modes

- Do not treat `supersigil verify` passing as proof that the code is
  correct. It proves the spec graph is internally consistent and that
  declared evidence exists. It does not run tests.
- Do not ignore `affected` output. Changed tracked files that do not
  trigger spec updates are a drift signal.
- Do not block PRs on info-level findings. They exist for iterative
  authoring awareness, not enforcement.

## Handoff

If CI reveals broken or missing specs, suggest `ss-feature-specification`
or `ss-retroactive-specification` to repair them.
If CI reveals implementation gaps (criteria without evidence), suggest
`ss-feature-development` to close the coverage.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jonisavo](https://github.com/jonisavo)
- **Source:** [jonisavo/supersigil](https://github.com/jonisavo/supersigil)
- **License:** Apache-2.0
- **Homepage:** https://supersigil.org

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jonisavo-supersigil-ss-ci-review
- Seller: https://agentstack.voostack.com/s/jonisavo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.