skill-design-lineage

Persist design documents with branch tracking, revision chains, and cross-session discovery

Quality

66%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/skill-design-lineage/SKILL.md

Design Document Lineage

Overview

Persist design documents from brainstorming and planning sessions with branch tracking, revision chains, and cross-session discoverability. Design docs are immutable after creation -- new revisions supersede prior versions rather than editing in place.

Storage Location

All design documents are stored under:

~/.claude-octopus/designs/<project-slug>/

The project slug is derived from the current git repository name or working directory basename:

SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"
mkdir -p "$DESIGNS_DIR"

Filename Format

Design documents follow a strict naming convention:

{user}-{branch}-design-{datetime}.md

Where:

{user} -- the current OS username ($USER or whoami)
{branch} -- the current git branch, sanitized (slashes replaced with dashes)
{datetime} -- ISO 8601 compact timestamp (YYYYMMDD-HHmmss)

Example:

chris-feature-auth-refactor-design-20260321-143022.md

Resolution:

BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")
DATETIME=$(date -u +"%Y%m%d-%H%M%S")
FILENAME="${USER}-${BRANCH}-design-${DATETIME}.md"

Design Document Template

Each design document contains YAML frontmatter followed by structured sections.

Frontmatter Metadata

---
branch: feature/auth-refactor
user: chris
created: 2026-03-21T14:30:22Z
supersedes: chris-feature-auth-refactor-design-20260320-091500.md
---

Fields:

branch -- the git branch at time of creation
user -- the OS username who created the document
created -- ISO 8601 timestamp of creation
supersedes -- filename of the prior design document this revision replaces (omitted if this is the first design for the branch)

Document Sections

# Design: [Title]

## Problem Statement
[What problem does this design solve? Why does it matter?]

## Constraints
[Technical, timeline, resource, or organizational constraints that bound the solution space.]

## Approaches Considered
[List each approach evaluated, with brief pros/cons for each.]

### Approach A: [Name]
- **Pros:** ...
- **Cons:** ...

### Approach B: [Name]
- **Pros:** ...
- **Cons:** ...

## Recommendation
[Which approach is recommended and why. Include the key trade-off that drove the decision.]

## Open Questions
[Unresolved questions that may affect implementation or require follow-up.]

Step 1: Save Design

After a brainstorm, planning, or define workflow produces design output, save it to the standard location with metadata.

SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"
mkdir -p "$DESIGNS_DIR"

BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")
DATETIME=$(date -u +"%Y%m%d-%H%M%S")
FILENAME="${USER}-${BRANCH}-design-${DATETIME}.md"
FILEPATH="${DESIGNS_DIR}/${FILENAME}"

cat > "$FILEPATH" <<EOF
---
branch: $(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "no-branch")
user: ${USER}
created: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
${SUPERSEDES:+supersedes: ${SUPERSEDES}}
---

# Design: [Title]

## Problem Statement
[Content from brainstorm/planning session]

## Constraints
[Identified constraints]

## Approaches Considered
[Evaluated approaches]

## Recommendation
[Selected approach and rationale]

## Open Questions
[Unresolved items]
EOF

Design docs are read-only after creation. To revise a design, create a new document with a supersedes reference to the prior version.

Step 2: Discover Prior Designs

Before writing a new design, search for related prior designs using keyword matching.

SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"

# Search for designs matching keywords (case-insensitive)
KEYWORDS="auth refactor"
grep -li "$KEYWORDS" "${DESIGNS_DIR}"/*.md 2>/dev/null | head -10

Constraints:

Keyword search is limited to 10 results to avoid overwhelming context
Search is case-insensitive via grep -li
Only searches within the current project slug's directory

When prior designs are found, present them to the user:

Found 2 prior designs related to "auth refactor":
  1. chris-feature-auth-refactor-design-20260320-091500.md (2026-03-20)
  2. chris-main-design-20260315-140000.md (2026-03-15)

Would you like to review any of these before creating a new design?

Step 3: Link Revision Chain

If a prior design exists for the same branch, the new design document includes a supersedes field in its frontmatter pointing to the prior filename.

BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")

# Find the most recent design for this branch
PRIOR=$(ls -t "${DESIGNS_DIR}"/*-${BRANCH}-design-*.md 2>/dev/null | head -1)

if [[ -n "$PRIOR" ]]; then
  SUPERSEDES=$(basename "$PRIOR")
fi

This creates a linked chain of revisions:

v3 (supersedes: v2) -> v2 (supersedes: v1) -> v1 (no supersedes)

To walk the full revision history for a branch:

current="$FILENAME"
while [[ -n "$current" ]]; do
  echo "$current"
  current=$(grep '^supersedes:' "${DESIGNS_DIR}/${current}" 2>/dev/null | sed 's/supersedes: *//' || true)
done

Step 4: Cross-Session Discovery

Downstream commands (deliver, review, develop) auto-discover design context by checking the designs directory before starting work.

SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")

# Find designs for current branch
BRANCH_DESIGNS=$(ls -t "${DESIGNS_DIR}"/*-${BRANCH}-design-*.md 2>/dev/null | head -3)

if [[ -n "$BRANCH_DESIGNS" ]]; then
  echo "Design context found for branch ${BRANCH}:"
  for design in $BRANCH_DESIGNS; do
    echo "  - $(basename "$design")"
  done
  # Read the most recent design for context
  LATEST_DESIGN=$(echo "$BRANCH_DESIGNS" | head -1)
  DESIGN_CONTEXT=$(<"$LATEST_DESIGN")
fi

Downstream skills should check for designs before starting work:

flow-discover: Check for existing designs to avoid duplicate research
flow-define: Incorporate prior design constraints into requirements
flow-develop: Read the recommended approach from the latest design
skill-brainstorm: Surface prior designs as starting context

Caps and Limits

Max 50 design docs per project slug -- when the limit is reached, warn the user and suggest archiving old designs
Keyword search limited to 10 results -- prevents context overload
Design doc template max 500 lines -- encourages concise, actionable designs

Cap enforcement:

DOC_COUNT=$(ls "${DESIGNS_DIR}"/*.md 2>/dev/null | wc -l | tr -d ' ')
if [[ "$DOC_COUNT" -ge 50 ]]; then
  echo "Warning: ${DOC_COUNT} design docs in ${DESIGNS_DIR}. Consider archiving old designs."
fi

Integration Notes

Works With

flow-discover -- Design docs capture research findings for persistence
flow-define -- Design constraints feed into requirement definitions
skill-brainstorm -- Brainstorm output can be saved as a design document
skill-thought-partner -- Exploration sessions can produce design artifacts

Downstream Discovery

flow-develop -- Reads latest design before implementation
flow-deliver -- References design decisions during review
skill-code-review -- Checks implementation against design recommendations

Immutability Rule

Design docs are read-only after creation. To update a design:

Create a new design document
Set supersedes to the prior document's filename
The prior document remains unchanged for audit trail

This ensures a complete history of design evolution is always available.

Repository: nyldn/claude-octopus
Path: .claude/skills/skill-design-lineage/SKILL.md
Commit: 9f39f0c

Last updated: 2 days ago
First committed: 2 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.