import{_ as a,o as i,c as n,a2 as t}from"./chunks/framework.CJEbdX1t.js";const d=JSON.parse('{"title":"Quickstart: Your First Spec in 5 Minutes","description":"","frontmatter":{},"headers":[],"relativePath":"getting-started/quickstart.md","filePath":"getting-started/quickstart.md"}'),e={name:"getting-started/quickstart.md"};function p(l,s,h,k,r,o){return i(),n("div",null,[...s[0]||(s[0]=[t(`<h1 id="quickstart-your-first-spec-in-5-minutes" tabindex="-1">Quickstart: Your First Spec in 5 Minutes <a class="header-anchor" href="#quickstart-your-first-spec-in-5-minutes" aria-label="Permalink to &quot;Quickstart: Your First Spec in 5 Minutes&quot;">​</a></h1><p>This tutorial walks you through creating a spec, getting it tracked by Specwright, and seeing the feedback loop in action.</p><h2 id="prerequisites" tabindex="-1">Prerequisites <a class="header-anchor" href="#prerequisites" aria-label="Permalink to &quot;Prerequisites&quot;">​</a></h2><ul><li>A GitHub repository with Specwright installed (see <a href="./installation.html">Installation</a>)</li><li>A <code>SPECWRIGHT.yaml</code> in your repo root</li></ul><h2 id="step-1-create-a-spec-file" tabindex="-1">Step 1: Create a Spec File <a class="header-anchor" href="#step-1-create-a-spec-file" aria-label="Permalink to &quot;Step 1: Create a Spec File&quot;">​</a></h2><p>Create <code>docs/specs/user-notifications.md</code>:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">title</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;User Notifications&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">status</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">draft</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">owner</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">your-name</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">team</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">product</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">ticket_project</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">PROJ</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">created</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2026-02-26</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">updated</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2026-02-26</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">tags</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">notifications</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">mvp</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># User Notifications</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Add email and in-app notifications for key user events.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## 1. Background</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Our users have no way to know when important events happen</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(new comments, status changes, approvals) without manually</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">checking the app. This leads to missed updates and slow</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">response times.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## 2. Email Notifications</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:system:2 status:todo --&gt;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Send email notifications for high-priority events.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">### Acceptance Criteria</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Email sent on new comment mentioning the user</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Email sent on spec status change (draft → in_progress)</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Unsubscribe link in every email</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Rate limit: max 10 emails per user per hour</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## 3. In-App Notifications</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:system:3 status:draft --&gt;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Show a notification bell with unread count in the app header.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">### Acceptance Criteria</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Notification bell shows unread count</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Click opens notification drawer</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Mark individual or all as read</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ ] Notifications persist for 30 days</span></span></code></pre></div><h2 id="step-2-commit-and-push" tabindex="-1">Step 2: Commit and Push <a class="header-anchor" href="#step-2-commit-and-push" aria-label="Permalink to &quot;Step 2: Commit and Push&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs/specs/user-notifications.md</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> commit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -m</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;spec: add user notifications spec&quot;</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> push</span></span></code></pre></div><h2 id="step-3-open-a-pr-that-implements-part-of-the-spec" tabindex="-1">Step 3: Open a PR That Implements Part of the Spec <a class="header-anchor" href="#step-3-open-a-pr-that-implements-part-of-the-spec" aria-label="Permalink to &quot;Step 3: Open a PR That Implements Part of the Spec&quot;">​</a></h2><p>Create a branch and implement one of the acceptance criteria:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> checkout</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -b</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> feat/email-notifications</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># ... implement email notifications ...</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> push</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -u</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> origin</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> feat/email-notifications</span></span></code></pre></div><p>Open a pull request. Within about 60 seconds, the Specwright bot comments:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>## Specwright</span></span>
<span class="line"><span></span></span>
<span class="line"><span>&gt; This PR implements email notification sending for user-notifications.md §2.</span></span>
<span class="line"><span></span></span>
<span class="line"><span>### Relevant Specs</span></span>
<span class="line"><span>**User Notifications** · docs/specs/user-notifications.md</span></span>
<span class="line"><span></span></span>
<span class="line"><span>| Section | |</span></span>
<span class="line"><span>|---------|---|</span></span>
<span class="line"><span>| §2 Email Notifications | Implements email sending logic |</span></span>
<span class="line"><span></span></span>
<span class="line"><span>### Realization Status</span></span>
<span class="line"><span>**User Notifications** § 2. Email Notifications</span></span>
<span class="line"><span></span></span>
<span class="line"><span>| AC | Status | Evidence |</span></span>
<span class="line"><span>|----|--------|----------|</span></span>
<span class="line"><span>| Email sent on new comment | ✅ Realized | \`src/notifications/email.py:42-60\` |</span></span>
<span class="line"><span>| Email sent on status change | ⬜ Not addressed | |</span></span>
<span class="line"><span>| Unsubscribe link | ✅ Realized | \`src/notifications/templates/base.html:15\` |</span></span>
<span class="line"><span>| Rate limit: max 10/hr | ⬜ Not addressed | |</span></span></code></pre></div><h2 id="step-4-iterate" tabindex="-1">Step 4: Iterate <a class="header-anchor" href="#step-4-iterate" aria-label="Permalink to &quot;Step 4: Iterate&quot;">​</a></h2><p>As you address more acceptance criteria in follow-up PRs, the spec sections auto-transition from <code>todo</code> → <code>in_progress</code> → <code>done</code>. Linked tickets close automatically when all ACs in a section are realized.</p><h2 id="what-s-next" tabindex="-1">What&#39;s Next? <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s Next?&quot;">​</a></h2><ul><li><a href="/docs/guides/writing-specs.html">Writing Specs</a> — Learn the full spec format and best practices</li><li><a href="./configuration.html">Configuration</a> — Customize Specwright for your workflow</li><li><a href="/docs/concepts/">Concepts</a> — Understand living specs, delta tracking, and the feedback loop</li></ul>`,18)])])}const g=a(e,[["render",p]]);export{d as __pageData,g as default};
