project-memory

name	project-memory
description	Read, update, and maintain structured project memory in docs/project_notes/ for the ArtStroy project. Use before proposing architectural changes, when encountering recurring bugs, when logging decisions, or when the user asks to record or recall project knowledge.

Project Memory for ArtStroy

ArtStroy maintains institutional knowledge in docs/project_notes/ inside the main repo (D:/QA_A/artstroy/). This skill governs how agents read, write, and search that memory.

Memory Files

docs/project_notes/
├── bugs.md         ← bug log with solutions and prevention notes
├── decisions.md    ← Architectural Decision Records (ADRs)
├── key_facts.md    ← configuration, URLs, constants, service accounts
└── issues.md       ← work log with ticket references and status

These files look like standard engineering documentation — not AI artifacts. Human developers read and maintain them too.

When to Read Memory

Always check before:

• Proposing an architectural change → read decisions.md
• Debugging a recurring-looking error → search bugs.md
• Looking up config (URLs, ports, credentials) → read key_facts.md
• Starting a new ticket → read issues.md for related prior work

Never assume. If the answer might be in memory, check first.

Searching Memory

Search by keyword across files:

grep -i "connection refused" docs/project_notes/bugs.md
grep "^### ADR-" docs/project_notes/decisions.md
grep -i "hetzner" docs/project_notes/key_facts.md
grep -A 3 "TICKET-" docs/project_notes/issues.md

Or search across all memory files at once:

grep -ri "pagefind" docs/project_notes/

Writing Memory Entries

Bug Entry (add to bugs.md)

### YYYY-MM-DD - Brief Bug Description
- **Issue**: what went wrong
- **Root Cause**: why it happened
- **Solution**: how it was fixed
- **Prevention**: how to avoid in the future

Decision Entry (add to decisions.md)

### ADR-XXX: Decision Title (YYYY-MM-DD)

**Context:**
- why the decision was needed

**Decision:**
- what was chosen

**Alternatives Considered:**
- Option A → why rejected
- Option B → why rejected

**Consequences:**
- benefits
- trade-offs

Key Fact Entry (add to key_facts.md)

Organize by category. Example categories: Hosting, CI/CD, API Keys, Local Development, URLs, Build.

## Hosting

- **Provider**: Hetzner Cloud (VPS, Frankfurt region)
- **Deploy method**: SSH → git pull → docker compose up -d
- **Docker Compose path**: `/srv/artstroy/docker-compose.yml`

Do NOT store secret values in key_facts.md. Secret locations belong there; secret values do not.

Work Log Entry (add to issues.md)

### YYYY-MM-DD - TICKET-ID: Brief Description
- **Status**: Completed / In Progress / Blocked
- **Description**: 1–2 line summary
- **URL**: https://github.com/AZANIR/artstroy/issues/XXX
- **Notes**: any important context

Memory Conflict Resolution

If a proposed action conflicts with an existing ADR:

1. Cite the ADR by number: "This conflicts with ADR-003 (use Bun, not npm)"
2. Either follow the existing decision or — if overriding is warranted — create a new ADR documenting the reversal
3. Never silently violate a documented decision

Maintenance Rules

• Keep entries concise: 1–3 lines per description
• Always include dates: entries without dates lose temporal context
• Include URLs: link to GitHub issues, PRs, relevant docs
• No automation: manual cleanup by humans; agents add but do not delete
• Decisions are permanent: keep all ADRs even if superseded (mark as SUPERSEDED BY ADR-XXX)
• Key facts decay: flag outdated config entries with [VERIFY: last confirmed YYYY-MM-DD]

ArtStroy-Specific Key Facts to Know

Always available in key_facts.md, do not repeat here — read the file. But be aware these categories exist:

• Hetzner server details (hostname, deploy path)
• Docker Compose service names
• GitHub repo (AZANIR/artstroy)
• Build command (bun run build = astro check && astro build)
• Content schema location (src/content/config.ts)
• Reference article (src/content/articles/owasp_api_security_top_10/index.mdx)