Waza Engineering Skills

Screenshot Iteration Mode is activated when you provide a screenshot or image of a rendered surface alongside a complaint (e.g., "fix this", "looks wrong", or specific feedback like "this is ugly"). This mode uses the existing product as the primary design direction and skips the standard five-question direction lock to focus on immediate visual fixes.

Workflow for UI Fixes

1. Diagnosis: The system reads the screenshot and states the specific problem (spacing, contrast, alignment, etc.) in one sentence. It preserves your specific negative labels rather than translating them into vague terms.
2. Confirmation: The system waits for you to confirm the diagnosis before modifying any code.
3. Comparison: If you provide a reference image or an older version, the system compares the current state vs. the reference and identifies visual deltas.
4. UX Research: For known UX patterns (e.g., sticky headers, infinite scroll), the system may survey how mature products handle the issue before coding, unless the fix is purely cosmetic.
5. Implementation: The system locates the exact code via grep, applies a minimal fix (prioritizing material, geometry, or typography over full redesigns), and verifies the result at both desktop and 375px mobile widths.
6. Verification: The system will always ask you to verify the result in your browser/app.

Redesign Priority Order

When reworking an existing UI, the system follows this order to maximize visual impact while minimizing code changes:

1. Font replacement
2. Color cleanup
3. Hover/active states
4. Layout and whitespace
5. Replace generic components
6. Add loading/empty/error states
7. Typographic polish

Boundaries and Routing

• Regressions/Bugs: If the screenshot shows a regression, broken render, or timing issue (rather than a matter of taste), the task is routed to /hunt.
• Scope Creep: If a fix requires changing 3 or more components or reveals a fundamental direction problem, the system will pause and trigger a full direction lock.

When a skill reads optional memory or prior-decision context, it must follow these scope and priority rules:

Scope

• Triggers: Read durable context when the user explicitly names memory, a prior decision, or a memory path, or when the project contains a MEMORY.md or a documented memory directory.
• Access Pattern: List titles first. Open at most one or two summaries.
• Restrictions: Do not hard-code machine-specific memory roots and do not read raw transcripts.
• Cross-project context: Treat entries from other projects as transferable patterns rather than facts about the current project.

Priority (Current State Wins)

Live state always overrides remembered memory. If a conflict occurs, name the conflict and follow the current state. The following are considered 'Current State' and take precedence over memory:

• Current code, diffs, and documentation
• Screenshots, logs, and tests
• CI, remote state, and live probes

Before publishing content externally, perform these three specific checks:

1. De-identify Sensitive Information: Ensure no details can trace back to the author's identity, such as employer, location, specific team background, or resume-style descriptions.
   • Bad: "As an engineer at X company..."
   • Good: "In medium-scale scenarios, this solution is most stable."
2. Avoid Attacking Competitors: Do not actively disparage similar products when introducing your own. If your product lacks a feature a competitor has, simply state what your product does rather than what it doesn't do.
   • Bad: "Unlike Typora, we..."
   • Good: "Our choice is to only index open files..."
3. Prioritize User Experience over Feature Lists: In release notes or tweets, do not start with a list of features. Start with a scenario or a feeling, then move into the technical changes.
   • Bad: "V1.2.0: Added X, fixed Y, optimized Z."
   • Good: "We fixed two things that felt awkward to use. First..."

Prioritize accuracy, clarity, and verifiability over 'removing AI flavor'.

• Context Preservation: Retain versions, platforms, dependencies, and risk boundaries. If information is missing, do not invent it; instead, use cautious language.
• Citations: When citing "official recommendations" or "documentation," provide specific sources. Avoid stating unverified claims as absolute truths.
• Code/Config Documentation: Do not just paste results. Explain key parameters, critical paths, and the rationale behind changes.
• Performance/Security Claims: Specify the observation method, including data sources, test environments, and sample ranges.
• Temporal Boundaries: For facts prone to obsolescence (prices, version numbers, product names), add boundary terms like 截至 2026-04 or 目前 to indicate the snapshot in time.
• Fact Verification: Always verify proper nouns (brand names, person names, product names) via official sources before editing.

When working with long drafts (roughly 10k+ characters, ~300+ lines, or files with multiple ## sections, tables, and images), use the Long-form Article Mode to address structural issues rather than just sentence-level polishing.

This mode is specifically designed to handle:

• Cross-section repetition: The same checklist, judgment list, or core claim appearing in multiple sections.
• Table re-reading: Prose that redundantly walks through the rows of a table located immediately above it.
• Redundancy: Entire sections or paragraphs that repeat information found elsewhere.

Workflow:

1. Map first (Read-only): The agent should first list every ## section, table, list, and image, flagging the structural problems mentioned above.
2. Propose cuts as change-points: Instead of silent deletions, the agent must show "before and after" snippets for structural cuts or merges and wait for user confirmation. This prevents the accidental loss of unique facts.
3. Line-level de-AI: Once structure is settled, perform section-by-section line editing.
4. Output change-points: The agent should provide diffs/change-points for review rather than a single rewritten blob.

Note: Only return a fully rewritten text block if explicitly requested (e.g., via the command 直接改 or just rewrite). If a full rewrite is requested, the agent must run the Punctuation Gate on the result first.

To read Feishu/Lark docx or wiki pages, you must first locate the fetch_feishu.py script within your Waza installation.

Setup

1. Install dependencies: pip install requests.
2. Set environment variables with your app credentials:
   • FEISHU_APP_ID
   • FEISHU_APP_SECRET
3. Ensure your app has docx:document:readonly and wiki:wiki:readonly permissions.

Usage

Run the script directly with the URL: python3 "$READ_SCRIPT_DIR/fetch_feishu.py" "{url}"

Output includes YAML frontmatter (title, document_id, url) and the Markdown body.

OAuth Fallback (lark-cli)

If API credentials are missing, you can use lark-cli for OAuth login:

1. npm install -g @larksuite/cli
2. lark-cli auth login
3. lark-cli docs +fetch --doc "{url}" --format json

Note: lark-cli returns structured JSON. You must extract and convert the content to Markdown before use.

# Setup environment
export FEISHU_APP_ID=your_app_id
export FEISHU_APP_SECRET=your_app_secret

# Execute fetch
python3 "$READ_SCRIPT_DIR/fetch_feishu.py" "{url}"

# OAuth Fallback
npm install -g @larksuite/cli
lark-cli auth login
lark-cli docs +fetch --doc "{url}" --format json

To perform a health audit, you must first run the collection script. The script identifies the correct path within the Waza skill base automatically.

Windows (PowerShell): Uses a specialized launcher to ensure Git for Windows tools are available in the child process.

$HEALTH_LAUNCHER = @(
  "<skill-base-dir>/scripts/run-health.ps1",
  "<skill-base-dir>/skills/health/scripts/run-health.ps1"
) | Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } | Select-Object -First 1
if (-not $HEALTH_LAUNCHER) {
  throw "Health launcher not found under the installed skill base; reinstall Waza."
}
powershell.exe -NoLogo -NoProfile -File "$HEALTH_LAUNCHER" collect

Linux and macOS (Bash):

HEALTH_SCRIPT=""
for candidate in \
  "<skill-base-dir>/scripts/collect-data.sh" \
  "<skill-base-dir>/skills/health/scripts/collect-data.sh"; do
  [ -f "$candidate" ] && HEALTH_SCRIPT="$candidate" && break
done
if [ ! -f "${HEALTH_SCRIPT:-}" ]; then
  echo "health collect-data.sh not found under the installed skill base; reinstall Waza"
  exit 1
fi
bash "$HEALTH_SCRIPT"

Note on dependencies:

• Missing jq makes conversation sections unavailable.
• Missing python3 makes MCP, hooks, and allowedTools sections unavailable.
• Missing settings.local.json may make hooks/MCP unavailable.