Skip to main content

Infrastructure Quick Reference Card

Print This

Print this page and keep it visible while working. One-page cheat sheet for mandatory infrastructure workflow.

The 5-Step Mandatory Workflow​

┌─────────────────────────────────────────────────────────────┐
│ BEFORE EVERY SESSION:                                       │
│   1. grep -ril "topic" docs/planning/decisions/  # Don't   │
│      reinvent                                               │
│   2. Check handoffs/ for ongoing context                    │
│                                                             │
│ DURING WORK:                                                │
│   3. Use sync profiles (not custom API clients)            │
│   4. Record decisions in docs/planning/decisions/           │
│   5. Document research in docs/planning/research-notes.md   │
│                                                             │
│ END OF SESSION:                                             │
│   6. Write handoff file if task is ongoing                  │
└─────────────────────────────────────────────────────────────┘

Decision Management​

Decisions are stored as markdown files in docs/planning/decisions/.

# Search before deciding (don't reinvent wheels)
grep -ril "topic" docs/planning/decisions/
grep -ril "database" docs/planning/decisions/
grep -ril "sync" docs/planning/decisions/

# List all decisions
ls docs/planning/decisions/

# List recent decisions
ls -lt docs/planning/decisions/ | head -10

# Read a decision
cat docs/planning/decisions/2026-02-03-use-supabase-postgresql.md

Create a new decision file:

# Use the naming pattern: YYYY-MM-DD-short-title.md
cat > docs/planning/decisions/$(date +%Y-%m-%d)-my-decision.md << 'EOF'
# Decision: [Title]

**Date:** YYYY-MM-DD
**Status:** Active
**Impact:** high
**Category:** architecture
**Department:** fp

## Decision

[What was decided.]

## Rationale

[Why this decision was made.]

## Alternatives Considered

- **Option A:** Why rejected
- **Option B:** Why rejected
EOF

Impact levels: critical | high | medium | low

Categories: architecture, process, tooling, infrastructure, security

Departments: fp, omg, lm, tech, legal, finance

Sync Operations​

# Activate environment
cd ~/GitHub/flypilot && source .venv/bin/activate

# See all profiles
python -m sync.cli profiles

# Quick sync (7 days, all platforms)
python -m sync.cli sync --profile quick

# Department-specific
python -m sync.cli sync --profile omg    # OMG only
python -m sync.cli sync --profile lrnd     # LRND only

# Full sync (30 days)
python -m sync.cli sync --profile full

# Test first (dry-run)
python -m sync.cli sync --profile quick --dry-run

# Check the logs
tail -100 ~/logs/flypilot-sync.log

Available profiles: quick, full, omg, lm, linear, shortcut, asana, weekly, monthly, annual

Memory & Research Notes​

Research findings are stored in docs/planning/research-notes.md and managed natively by the AI platform (Claude Code project memory, Gemini project memory).

# Add a finding to the research notes file
echo "- $(date +%Y-%m-%d): Finding here — tags: topic,system" \
  >> docs/planning/research-notes.md

# Search existing findings
grep -i "keyword" docs/planning/research-notes.md
grep -i "toggl" docs/planning/research-notes.md
grep -i "api limit" docs/planning/research-notes.md

Best practices:

  • Document findings immediately, not at end of day
  • Use searchable terms — grep is how you'll find them later
  • Distinguish findings (facts) from decisions (choices)

Session Continuity​

Sessions are managed natively by the AI platform. Use handoff files for cross-session context.

# Check for ongoing work context
ls handoffs/
cat handoffs/session-Tech-Director-2026-02-24.md

# Create a handoff when leaving ongoing work
cat > handoffs/session-$(date +%Y-%m-%d).md << 'EOF'
# Session Handoff

## Context
[What were you working on?]

## Completed
- [What got done]

## Next Steps
- [What to do next]
EOF

Rate Limiting (Automatic)​

You Don't Need to Do Anything

Rate limiting is automatic. The sync system handles all rate limiting.

If you see errors:

# Check rate limit status
tail -100 ~/logs/flypilot-sync.log | grep -i "rate"

# Wait for reset (shown in error message)
# Or use a different profile (smaller date range)

Rate limits (per hour):

  • Asana: 1500 requests
  • Shortcut: 1000 requests
  • Linear: 1000 requests

Common Scenarios​

Starting a New Task​

# 1. Search for related decisions
grep -ril "topic keywords" docs/planning/decisions/

# 2. Check for ongoing handoffs
ls handoffs/

# 3. Do the work...

Making an Architectural Decision​

# 1. Search for conflicts
grep -ril "proposed approach" docs/planning/decisions/

# 2. Record the decision
cat > docs/planning/decisions/$(date +%Y-%m-%d)-use-postgresql-for-agent-state.md << 'EOF'
# Decision: Use PostgreSQL for agent state

**Date:** 2026-02-25
**Status:** Active
**Impact:** high
**Category:** architecture
**Department:** fp

## Decision

Use PostgreSQL (via Supabase) for all agent state storage.

## Rationale

Better transactional support, easier migrations.

## Alternatives Considered

- **SQLite:** Simpler but limited for concurrent access
- **JSON files:** No schema enforcement
EOF

Syncing Data​

# 1. Choose profile
python -m sync.cli profiles

# 2. Test first
python -m sync.cli sync --profile quick --dry-run

# 3. Run for real
python -m sync.cli sync --profile quick

Ending Your Work Session​

# 1. Document any key findings
echo "- $(date +%Y-%m-%d): [Important finding]" >> docs/planning/research-notes.md

# 2. Record any decisions made
ls docs/planning/decisions/ | tail -3

# 3. Write handoff if work continues tomorrow
# (See Session Continuity section above)

# 4. Check sync logs for anything needing attention
tail -20 ~/logs/flypilot-sync.log
tail -20 ~/logs/flypilot-wpengine-alerts.log

Keyboard Shortcuts (Optional Aliases)​

Add to ~/.zshrc or ~/.bashrc:

# Decision management (grep-based)
alias dsearch='grep -ril'  # Usage: dsearch "keyword" ~/GitHub/flypilot/docs/planning/decisions/
alias dlist='ls -lt ~/GitHub/flypilot/docs/planning/decisions/ | head -20'

# Sync operations
alias syncq='cd ~/GitHub/flypilot && source .venv/bin/activate && python -m sync.cli sync --profile quick'
alias synco='cd ~/GitHub/flypilot && source .venv/bin/activate && python -m sync.cli sync --profile omg'
alias syncl='cd ~/GitHub/flypilot && source .venv/bin/activate && python -m sync.cli sync --profile lrnd'
alias syncp='cd ~/GitHub/flypilot && source .venv/bin/activate && python -m sync.cli profiles'

# Logs
alias logsync='tail -100 ~/logs/flypilot-sync.log'
alias logwpe='tail -100 ~/logs/flypilot-wpengine.log'
alias logalert='tail -100 ~/logs/flypilot-wpengine-alerts.log'

Success Metrics​

Daily:

  • ✅ Reviewed past decisions before implementing
  • ✅ Recorded at least 1 decision as a file
  • ✅ Documented key research findings
  • ✅ Used sync profiles (not custom code)

Weekly:

  • ✅ 5-10 decisions recorded
  • ✅ Research notes kept up to date
  • ✅ 0 rate limit errors
  • ✅ 0 infrastructure bypasses

Monthly:

  • ✅ 30+ decisions recorded
  • ✅ Growing research notes library
  • ✅ Infrastructure is habitual

Troubleshooting​

"Can't find past decisions"​

# Broaden the search
grep -ril "keyword" docs/planning/decisions/

# List all decisions and scan visually
ls -lt docs/planning/decisions/

"Command not found: sync.cli"​

cd ~/GitHub/flypilot
source .venv/bin/activate

"Rate limit error"​

# Wait for reset (shown in error)
# Or use smaller profile
python -m sync.cli sync --profile quick  # 7 days instead of 30

What NOT To Do​

❌ Skip searching decisions before implementing ❌ Write custom API clients (use sync profiles) ❌ Record decisions only in Slack or PR descriptions ❌ Leave research findings undocumented ❌ Bypass infrastructure "just this once"

✅ Follow the 5-step workflow ✅ Use infrastructure tools ✅ Record all decisions as markdown files ✅ Document research findings ✅ Make it habitual

Remember

Time investment: 2-3 min per session

Time saved: 30-60 min per session (not redoing work)

ROI: 10-20x

The goal is not perfection. The goal is consistency.

Use the workflow every time. It becomes automatic within 2 weeks.