exekiel179/spss-mcp/spss-mcp-guard

SPSS MCP Guard

Use this skill to make SPSS MCP execution robust, especially for uncommon procedures, long-running analyses, and syntax that may vary by SPSS version.

Workflow

1. Check capability first

• Call spss_check_status.
• If SPSS batch is unavailable, stop and explain that only file-mode tools are safe.

1. Read the data before writing syntax

• Use spss_file_summary or spss_read_metadata first.
• Never guess variable names or data shape.

1. Prefer the safest execution path

• Use a dedicated MCP tool when one exists and is known-good.
• Use spss_run_syntax for uncommon methods, but only after a smoke test.

1. Smoke test before heavy analysis

• First run a minimal procedure such as:
• DESCRIPTIVES
• FREQUENCIES
• DISPLAY DICTIONARY
• Only attempt heavier methods after the smoke test succeeds.

1. Escalate analysis gradually

• Start with the smallest sample or simplest valid syntax.
• Add options one subcommand at a time.
• For MDS/PROXSCAL-style work, first validate the command family and legal keywords by interpreting SPSS warnings.

1. Treat SPSS warnings as syntax guidance

• If SPSS says a keyword is unrecognized, rewrite syntax to match the reported valid keywords.
• Do not keep retrying the same syntax.

1. Distinguish timeout from syntax failure

• A long wait is not always a true performance issue.
• If possible, probe the same command through a minimal direct execution path before concluding it is only a timeout issue.

Guardrails

• Do not jump directly to complex procedures on first attempt.
• Do not assume old SPSS syntax examples match the installed version.
• Do not assume .env settings are loaded; verify behavior if timeout values look stale.
• Do not treat success=True as “analysis valid” without reading warning blocks.
• For uncommon procedures, keep the first successful run minimal, then add output options later.

Decision Tree

1. Execution fails immediately?

• Check spss_check_status.
• Verify data path and variables with file tools.

1. Execution times out?

• Re-run a minimal baseline procedure on the same file.
• If baseline succeeds, suspect syntax/procedure complexity rather than global SPSS failure.
• Inspect timeout configuration behavior before increasing complexity.

1. SPSS returns warnings/errors but output exists?

• Read the warning text carefully.
• Use it to rewrite subcommands.
• Especially common for PRINT, MODEL, and SHAPE subcommands in advanced procedures.

1. Procedure is unfamiliar or cold-path?

• Use spss_run_syntax.
• Start with minimal valid syntax.
• Add optional subcommands only after the base command works.

Known reliable patterns

• For a baseline smoke test:

DESCRIPTIVES VARIABLES=x1 x2 x3
  /STATISTICS=MEAN STDDEV MIN MAX.

• For defensive PROXSCAL probing, prefer minimal legal syntax first. Do not assume keywords like SYMMETRIC, EUCLID, or CONFIGURATION are valid in the installed SPSS syntax variant without testing.

References

• Read references/failure-patterns.md when diagnosing timeouts, invalid keywords, stale .env behavior, or advanced procedure incompatibilities.
• Reuse spss-analyst for general SPSS workflow and syntax conventions; this skill is specifically for failure prevention and recovery.