skills: ask user for output directory before running commands

Without this, the agent picks an output directory on its own (e.g.
odf/namespace-application) and the user has no way to change it.

Add a "Pick an output directory" step to the validate-application,
gather-application, test-run, and test-clean skills. The
validate-clusters skill already had this step but used a vague <env>
placeholder.

All skills now suggest out/ as the base directory and ask the agent
to use a new directory for each run. If the directory already exists
the agent suggests a name with a datetime suffix (e.g.
out/clusters-2026-07-20-19-46). Reusing a directory causes output
files with numeric suffixes (-2, -3) that confuse the agent when
inspecting results.

Also rename <output-dir> to <output-directory> to match the step
heading and reinforce that the agent should use the directory chosen
in the previous step.

Assisted-by: Cursor/Claude Opus 4.6
Signed-off-by: Nir Soffer <nsoffer@redhat.com>

Author: nirs

pkg/skills/templates/skills/gather-application.tmpl

@@ -35,30 +35,36 @@ argocd      appset-deploy-rbd      69m   dr1                dr2               Re
 Present the list and let the user choose which application to gather
 data for.
 
-### Step 2: Run gather application
+### Step 2: Pick an output directory
 
-Use `<env>/<namespace>-<app-name>` for the output directory, e.g., `myenv/myns-myapp`.
+Ask the user where to store the output. Suggest
+`out/<namespace>-<app-name>`, e.g., `out/myns-myapp`.
+
+If the directory already exists, suggest another name such as
+`out/<namespace>-<app-name>-<YYYY-MM-DD-HH-MM>` (e.g., `out/myns-myapp-2026-07-20-19-46`).
+
+### Step 3: Run gather application
 
 ```console
-$ {{.Command.Name}} gather application --name <drpc-name> --namespace <namespace> -o <output-dir>
+$ {{.Command.Name}} gather application --name <drpc-name> --namespace <namespace> -o <output-directory>
 ```
 
 Use `--config <file>` if the config file is not the default `config.yaml`.
 
 The command takes a few seconds on local clusters and about a minute on
 remote clusters.
 
-### Step 3: Check the result
+### Step 4: Check the result
 
 On success the command ends with:
 
 ```console
 ✅ Gather completed
 ```
 
-On failure, check `<output-dir>/gather-application.log` for details.
+On failure, check `<output-directory>/gather-application.log` for details.
 
-### Step 4: Inspect gathered data
+### Step 5: Inspect gathered data
 
 The output directory contains:
 
@@ -76,7 +82,7 @@ resources. Ramen operator logs are gathered under
 `namespaces/ramen-system/pods/`.
 
 ```console
-$ tree -L3 <output-dir>/gather-application.data
+$ tree -L3 <output-directory>/gather-application.data
 gather-application.data/
 ├── dr1/
 │   ├── cluster/

pkg/skills/templates/skills/test-clean.tmpl

@@ -23,20 +23,23 @@ Delete resources created by `{{.Command.Name}} test run`.
 
 ## Workflow
 
-### Step 1: Run test clean
+### Step 1: Pick an output directory
 
-Use the same output directory and config file as the test run:
+Ask the user where to store the report. Suggest using the same output
+directory as the test run, but a different directory also works.
+
+### Step 2: Run test clean
 
 ```console
-$ {{.Command.Name}} test clean -o <output-dir>
+$ {{.Command.Name}} test clean -o <output-directory>
 ```
 
 Use `--config <file>` if the config file is not the default `config.yaml`.
 
 The command unprotects and undeploys test applications, then cleans the
 test environment (channels, namespaces).
 
-### Step 2: Check the result
+### Step 3: Check the result
 
 **On success:**
 

pkg/skills/templates/skills/test-run.tmpl

@@ -22,12 +22,17 @@ in the configuration file.
 
 ## Workflow
 
-### Step 1: Run the test
+### Step 1: Pick an output directory
 
-Use `<env>/test` for the output directory, e.g., `myenv/test`.
+Ask the user where to store the report. Suggest `out/test`.
+
+If the directory already exists, suggest another name such as
+`out/test-<YYYY-MM-DD-HH-MM>` (e.g., `out/test-2026-07-20-19-46`).
+
+### Step 2: Run the test
 
 ```console
-$ {{.Command.Name}} test run -o <output-dir>
+$ {{.Command.Name}} test run -o <output-directory>
 ```
 
 Use `--config <file>` if the config file is not the default `config.yaml`.
@@ -38,7 +43,7 @@ deploy, protect, failover, relocate, unprotect, undeploy.
 **This typically takes 15-20 minutes per test case.** Multiple test cases
 run in parallel.
 
-### Step 2: Check the result
+### Step 3: Check the result
 
 **On success:**
 
@@ -53,7 +58,7 @@ clusters and S3 into `test-run.data/`:
 ❌ failed (N passed, M failed, 0 skipped)
 ```
 
-### Step 3: Inspect the report
+### Step 4: Inspect the report
 
 The output directory contains:
 
@@ -68,25 +73,25 @@ Useful commands:
 Overall status:
 
 ```console
-$ yq '.status' < <output-dir>/test-run.yaml
+$ yq '.status' < <output-directory>/test-run.yaml
 ```
 
 Individual step status and durations:
 
 ```console
-$ yq '.steps[-1].items' < <output-dir>/test-run.yaml
+$ yq '.steps[-1].items' < <output-directory>/test-run.yaml
 ```
 
 Test events from the log:
 
 ```console
-$ grep -E '(INFO|ERROR).+<app-name>' <output-dir>/test-run.log
+$ grep -E '(INFO|ERROR).+<app-name>' <output-directory>/test-run.log
 ```
 
 The `test-run.yaml` report contains the config used, each test step with
 its status and duration, and a summary with pass/fail/skip counts.
 
-### Step 4: Handle failures
+### Step 5: Handle failures
 
 If the test failed:
 
@@ -98,7 +103,7 @@ If the test failed:
 4. Fix the underlying issue
 5. **Always clean up** before re-running (see {{.Command.Slug}}-test-clean skill)
 
-### Step 5: Clean up
+### Step 6: Clean up
 
 Ask the user if they want to clean up. Do not clean up without an
 explicit request — failed test resources are evidence for debugging.

pkg/skills/templates/skills/validate-application.tmpl

@@ -38,12 +38,18 @@ Present the list and let the user choose which application to validate.
 The `NAME` and `NAMESPACE` columns map to the `--name` and `--namespace`
 flags.
 
-### Step 2: Run validate application
+### Step 2: Pick an output directory
 
-Use `<env>/<namespace>-<app-name>` for the output directory, e.g., `myenv/myns-myapp`.
+Ask the user where to store the report. Suggest
+`out/<namespace>-<app-name>`, e.g., `out/myns-myapp`.
+
+If the directory already exists, suggest another name such as
+`out/<namespace>-<app-name>-<YYYY-MM-DD-HH-MM>` (e.g., `out/myns-myapp-2026-07-20-19-46`).
+
+### Step 3: Run validate application
 
 ```console
-$ {{.Command.Name}} validate application --name <drpc-name> --namespace <namespace> -o <output-dir> --interactive=false
+$ {{.Command.Name}} validate application --name <drpc-name> --namespace <namespace> -o <output-directory> --interactive=false
 ```
 
 `--interactive=false` prevents {{.Command.Name}} from opening a browser—you open the
@@ -54,7 +60,7 @@ Use `--config <file>` if the config file is not the default `config.yaml`.
 The command takes a few seconds on local clusters and about a minute on
 remote clusters.
 
-### Step 3: Check the result
+### Step 4: Check the result
 
 **On success:**
 
@@ -73,16 +79,16 @@ there are problems **in** that report. If the command **fails before** a
 report is written (early error), there may be no HTML—use the log and console
 output instead.
 
-### Step 4: Open the HTML report
+### Step 5: Open the HTML report
 
-If `<output-dir>/validate-application.html` exists, open it in the
+If `<output-directory>/validate-application.html` exists, open it in the
 browser using `open <path>` (macOS), `xdg-open <path>` (Linux), or
 `cmd /c start "" <path>` (Windows). Do not skip unless the user asks
 to skip.
 
 The report may not exist if the command failed before writing it.
 
-### Step 5: Inspect the report
+### Step 6: Inspect the report
 
 The output directory contains:
 
@@ -96,13 +102,13 @@ The output directory contains:
 Read the application status:
 
 ```console
-$ yq '.applicationStatus' < <output-dir>/validate-application.yaml
+$ yq '.applicationStatus' < <output-directory>/validate-application.yaml
 ```
 
 #### Gathered data structure
 
 ```console
-$ tree -L3 <output-dir>/validate-application.data
+$ tree -L3 <output-directory>/validate-application.data
 validate-application.data/
 ├── <cluster>/
 │   ├── cluster/
@@ -117,7 +123,7 @@ validate-application.data/
         └── <app-namespace>/
 ```
 
-### Step 6: Troubleshoot problems
+### Step 7: Troubleshoot problems
 
 This section is an **initial draft** — DR troubleshooting is hard and
 needs more playbooks over time (for example a future analyze skill).
@@ -134,20 +140,20 @@ Useful commands for inspecting gathered data:
 Check VRG status:
 
 ```console
-$ yq '.status' < <output-dir>/validate-application.data/<cluster>/namespaces/<ns>/ramendr.openshift.io/volumereplicationgroups/<name>.yaml
+$ yq '.status' < <output-directory>/validate-application.data/<cluster>/namespaces/<ns>/ramendr.openshift.io/volumereplicationgroups/<name>.yaml
 ```
 
 Search ramen operator logs for errors related to the app:
 
 ```console
-$ grep -E 'ERROR.+<app-name>' <output-dir>/validate-application.data/<cluster>/namespaces/ramen-system/pods/*/manager/current.log
+$ grep -E 'ERROR.+<app-name>' <output-directory>/validate-application.data/<cluster>/namespaces/ramen-system/pods/*/manager/current.log
 ```
 
-### Step 7: Suggest validate clusters
+### Step 8: Suggest validate clusters
 
 After completing the application validation, suggest also running
 `{{.Command.Name}} validate clusters` into a sibling output directory such as
-`<env>/clusters`. When they agree (or you run it for them), follow the
+`out/clusters`. When they agree (or you run it for them), follow the
 **{{.Command.Slug}}-validate-clusters** skill end to end.
 
 Why this helps: the application report covers one DRPC, its namespaces, and

pkg/skills/templates/skills/validate-clusters.tmpl

@@ -22,13 +22,15 @@ resources from all clusters, and checking that S3 endpoints are accessible.
 
 ### Step 1: Pick an output directory
 
-Ask the user where to store the report. Suggest `<env>/clusters` or
-`<env>-<date>/clusters`, e.g., `myenv/clusters`.
+Ask the user where to store the report. Suggest `out/clusters`.
+
+If the directory already exists, suggest another name such as
+`out/clusters-<YYYY-MM-DD-HH-MM>` (e.g., `out/clusters-2026-07-20-19-46`).
 
 ### Step 2: Run validate clusters
 
 ```console
-$ {{.Command.Name}} validate clusters -o <output-dir> --interactive=false
+$ {{.Command.Name}} validate clusters -o <output-directory> --interactive=false
 ```
 
 `--interactive=false` prevents {{.Command.Name}} from opening a browser—you open the
@@ -61,7 +63,7 @@ output instead.
 
 ### Step 4: Open the HTML report
 
-If `<output-dir>/validate-clusters.html` exists, open it in the
+If `<output-directory>/validate-clusters.html` exists, open it in the
 browser using `open <path>` (macOS), `xdg-open <path>` (Linux), or
 `cmd /c start "" <path>` (Windows). Do not skip unless the user asks
 to skip.
@@ -82,13 +84,13 @@ The output directory contains:
 Read the YAML report to understand the status:
 
 ```console
-$ yq '.clustersStatus' < <output-dir>/validate-clusters.yaml
+$ yq '.clustersStatus' < <output-directory>/validate-clusters.yaml
 ```
 
 #### Gathered data structure
 
 ```console
-$ tree -L3 <output-dir>/validate-clusters.data
+$ tree -L3 <output-directory>/validate-clusters.data
 validate-clusters.data/
 ├── <cluster>/
 │   ├── cluster/